Commit 9952a502 authored by Nigel Kukard's avatar Nigel Kukard
Browse files

Added information on introspection

parent daabb16e
......@@ -118,6 +118,45 @@ There is a caveat about DELETE idempotence, however. Calling DELETE on a resourc
## OPTIONS
Introspection using the OPTIONS method. This allows for both introspection of collection methods available and introspection of
record information.
Using the OPTIONS method on the root path of the URI followed by a \* should provide a list of collections available.
Using the OPTIONS method on a collection :record_id path should provide information on the record structure.
The 204 error code should be returned if OPTIONS is not implemented for the requested resource.
### Return Codes
* 404 (Not Found)
* 200 (OK)
* 204 (No Content)
### Examples
* OPTIONS http://www.example.com/\*
* OPTIONS http://www.example.com/customers
* OPTIONS http://www.example.com/customers/:record_id
## PROPFIND
Collection properties using PROPFIND. This will allow the return of properties for the collection as a whole.
Using the PROPFIND method on the root path of the URI should return information on the API.
The 204 error code should be returned if OPTIONS is not implemented for the requested resource.
### Return Codes
* 404 (Not Found)
* 200 (OK)
* 204 (No Content)
### Examples
* PROPFIND http://www.example.com/customers
# Format
......@@ -241,6 +280,188 @@ See the 'status' field definition above for examples.
# Examples
## Introspection example
### API information using /
Using the PROPFIND method request to http://www.example.com may look like this...
```jsonnet
{
"status": "success",
"data": {
"title": "Issue Tracker App",
"description": "This is a sample server for issue tracking.",
"termsOfService": "http://www.example.com/terms",
"contact": {
"name": "API Support",
"url": "http://www.example.com/contact",
"email": "support@example.com"
},
"version": "0.0.1"
}
}
```
### Collection list using path /*
An OPTIONS method request to http://www.example.com/\* may look like this...
```jsonnet
{
"status": "success",
"data": {
"result": {
"collections": [
"/issues"
]
}
}
}
```
### Collection information
A OPTIONS method request to http://www.example.com/issues may look like this...
```jsonnet
{
"POST": {
"description": "Create an issue",
"path": "/issues",
"parameters": {
"title": {
"type": "string"
"description": "Issue title.",
"required": true
},
"body": {
"type": "string",
"description": "Issue body.",
},
"assignee": {
"type": "string",
"description" "Login for the user that this issue should be assigned to."
},
"milestone": {
"type": "number",
"description": "Milestone to associate this issue with."
},
"labels": {
"type": "array/string"
"description": "Labels to associate with this issue."
}
},
"returns": {
"status": {
"type": "status",
"description": "Result of request"
},
"data": {
"type": "hash",
"description": "Data hash containing record details, returned only on success",
"children": {
"record_id": {
"type": "integer",
"description": "ID of the created record"
}
}
}
}
"example": {
"title": "Found a bug",
"body": "I'm having a problem with this.",
"assignee": "octocat",
"milestone": 1,
"labels": [
"Label1",
"Label2"
]
}
}
"DELETE": {
"description": "Delete an item",
"path": "/issues/:record_id",
"parameters": {
"record_id": {
"type": "integer"
"description": "Record ID",
"required": true
},
},
"returns": {
"status": {
"type": "status",
"description": "Result of request"
},
}
}
"PATCH": {
"description": "Change an item",
"path": "/issues/:record_id",
"parameters": {
"record_id": {
"type": "integer"
"description": "Record ID",
"required": true
},
},
"returns": {
"status": {
"type": "status",
"description": "Result of request"
},
}
}
"PUT": {
"description": "Replace an item",
"path": "/issues/:record_id",
"parameters": {
"record_id": {
"type": "integer"
"description": "Record ID",
"required": true
},
},
"returns": {
"status": {
"type": "status",
"description": "Result of request"
},
}
},
"OPTIONS": {
"description": "Record information",
"path": "/issues/:record_id",
"parmaeters": {
":record_id": {
"type": "string",
"description": "This is a string literal ':record_id'",
"required": "This is a string literal ':record_id'",
}
},
"returns": {
"status": {
"type": "status",
"description": "Result of request"
},
}
},
"PROPFIND": {
"description": "Collection information",
"path": "/issues",
"parameters": { },
"returns": {
"records": {
"type": "integer",
"description": "Number of items in collection",
}
}
}
}
```
# Acknoledgements
<div xmlns:cc="http://creativecommons.org/ns#" about="http://www.restapitutorial.com/lessons/httpmethods.html"><a rel="cc:attributionURL" property="cc:attributionName" href="http://www.RestApiTutorial.com">RestApiTutorial.com</a> / <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a></div>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment