Commit e0b07dd9 authored by Nigel Kukard's avatar Nigel Kukard
Browse files

Merge branch 'introspection' into 'master'

Spec overhaul including introspection

See merge request !18
parents daabb16e ab82b710
# AWIT JSON Format Standard
# HTTP Methods
Make sure during implementation you read [RFC7231](https://tools.ietf.org/html/rfc7231).
## POST
The POST verb is most-often utilized to **create** new resources. In particular, it's used to create subordinate resources. That is, subordinate to some other (e.g. parent) resource. In other words, when creating a new resource, POST to the parent and the service takes care of associating the new resource with the parent, assigning an ID (new resource URI), etc.
On successful creation, return HTTP status 201, returning a Location header with a link to the newly-created resource with the 201 HTTP status.
The POST method is utilized to **create** new resources. POST to a parent resource must associate the new resource with the parent,
assigning an ID (new resource URI), etc.
POST is neither safe nor idempotent. It is therefore recommended for non-idempotent resource requests. Making two identical POST requests will most-likely result in two resources containing the same information.
On successful creation, return HTTP status 201, returning a Location header with a link to the newly-created resource with the 201
HTTP status.
### Return Codes
* 201 (Created)
......@@ -26,11 +27,8 @@ POST is neither safe nor idempotent. It is therefore recommended for non-idempot
## GET
The HTTP GET method is used to **read** (or retrieve) a representation of a resource. In the “happy” (or non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).
According to the design of the HTTP specification, GET (along with HEAD) requests are used only to read data and not change it. Therefore, when used this way, they are considered safe. That is, they can be called without risk of data modification or corruption—calling it once has the same effect as calling it 10 times, or none at all. Additionally, GET (and HEAD) is idempotent, which means that making multiple identical requests ends up having the same result as a single request.
Do not expose unsafe operations via GET—it should never modify any resources on the server.
The GET method is used to **read** a resource. In a non-error path, GET returns a HTTP status of 200 (OK). In an error case,
it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).
### Return Codes
* 200 (OK)
......@@ -47,66 +45,47 @@ Do not expose unsafe operations via GET—it should never modify any resources o
## PUT
PUT is most-often utilized for **replace** capabilities, PUT-ing to a known resource URI with the request body containing the newly-replaced representation of the original resource.
However, PUT can also be used to create a resource in the case where the resource ID is chosen by the client instead of by the server. In other words, if the PUT is to a URI that contains the value of a non-existent resource ID. Again, the request body contains a resource representation. Many feel this is convoluted and confusing. Consequently, this method of creation should be used sparingly, if at all.
The PUT method is utilized for **replace**, PUT-ing to a known resource URI with the request body containing the replacement
resource data.
Alternatively, use POST to create new resources and provide the client-defined ID in the body representation—presumably to a URI that doesn't include the ID of the resource (see POST below).
On successful update, return 200 (or 204 if not returning any content in the body) from a PUT. If using PUT for create, return HTTP status 201 on successful creation. A body in the response is optional—providing one consumes more bandwidth. It is not necessary to return a link via a Location header in the creation case since the client already set the resource ID.
PUT is not a safe operation, in that it modifies (or creates) state on the server, but it is idempotent. In other words, if you create or update a resource using PUT and then make that same call again, the resource is still there and still has the same state as it did with the first call.
If, for instance, calling PUT on a resource increments a counter within the resource, the call is no longer idempotent. Sometimes that happens and it may be enough to document that the call is not idempotent. However, it's recommended to keep PUT requests idempotent. It is strongly recommended to use POST for non-idempotent requests.
On successful replacement, return 200 (or 204 if no changes were made).
### Return Codes
* 404 (Not Found)
* WIP: Unless you want to update/replace every resource in the entire collection.
* 200 (OK)
* 204 (No Content)
* If no changes were made.
* 404 (Not Found)
* If ID not found or invalid.
### Examples
* PUT http://www.example.com/customers/12345
* PUT http://www.example.com/customers/12345/orders/98765
* PUT http://www.example.com/buckets/secret_stuff
## PATCH
PATCH is used for **modify** capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.
The PATCH method is used for **modify**. The PATCH request only needs to contain the changes to the resource, not the complete
resource.
This resembles PUT, but the body contains a set of instructions describing how a resource currently residing on the server should be modified to produce a new version. This means that the PATCH body should not just be a modified part of the resource, but in some kind of patch language like JSON Patch or XML Patch.
PATCH is neither safe nor idempotent. However, a PATCH request can be issued in such a way as to be idempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame. Collisions from multiple PATCH requests may be more dangerous than PUT collisions because some patch formats need to operate from a known base-point or else they will corrupt the resource. Clients using this kind of patch application should use a conditional request such that the request will fail if the resource has been updated since the client last accessed the resource. For example, the client can use a strong ETag in an If-Match header on the PATCH request.
On successful modification, return 200 (or 204 if no changes were made).
### Return Codes
* 404 (Not Found)
* WIP: Unless you want to modify the collection itself.
* 200 (OK)
* 204 (No Content)
* If no changes were made.
* 404 (Not Found)
* If ID not found or invalid.
### Examples
* PATCH http://www.example.com/customers/12345
* PATCH http://www.example.com/customers/12345/orders/98765
* PATCH http://www.example.com/buckets/secret_stuff
## DELETE
DELETE is pretty easy to understand. It is used to **delete** a resource identified by a URI.
On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted item (often demands too much bandwidth), or a wrapped response (see Return Values below). Either that or return HTTP status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style response and HTTP status 200 are the recommended responses.
DELETE is used to **delete** a resource identified by a URI.
HTTP-spec-wise, DELETE operations are idempotent. If you DELETE a resource, it's removed. Repeatedly calling DELETE on that resource ends up the same: the resource is gone. If calling DELETE say, decrements a counter (within the resource), the DELETE call is no longer idempotent. As mentioned previously, usage statistics and measurements may be updated while still considering the service idempotent as long as no resource data is changed. Using POST for non-idempotent resource requests is recommended.
There is a caveat about DELETE idempotence, however. Calling DELETE on a resource a second time will often return a 404 (NOT FOUND) since it was already removed and therefore is no longer findable. This, by some opinions, makes DELETE operations no longer idempotent, however, the end-state of the resource is the same. Returning a 404 is acceptable and communicates accurately the status of the call.
On successful deletion, return HTTP status 200 (OK).
### Return Codes
* 404 (Not Found)
* Unless you want to delete the whole collection, not often desirable.
* 200 (OK)
* 404 (Not Found)
* If ID not found or invalid.
......@@ -114,11 +93,50 @@ There is a caveat about DELETE idempotence, however. Calling DELETE on a resourc
### Examples
* DELETE http://www.example.com/customers/12345
* DELETE http://www.example.com/customers/12345/orders
* DELETE http://www.example.com/bucket/sample
## OPTIONS
The OPTIONS method is used for introspection. 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)
* If OPTIONS is not implemented for this resource.
### Examples
* OPTIONS http://www.example.com/\*
* OPTIONS http://www.example.com/customers
* OPTIONS http://www.example.com/customers/:record_id
## PROPFIND
The PROPFIND method is used for introspection. This will allow the return of properties for a collection as a whole. It can also
be used to determine properties of arbitrary resources.
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)
* If PROPFIND is not implemented for this resource.
### Examples
* PROPFIND http://www.example.com/customers
# Format
# Data Format
## The 'status' field
......@@ -232,7 +250,6 @@ The purpose of this key is to give a quick status message as to the result of th
The format of this keys data is plain text.
## The 'data' field
This field contains result data. Either a 'result' key or a 'records' key.
......@@ -241,7 +258,190 @@ See the 'status' field definition above for examples.
# Examples
## Introspection examples
### 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>
Inspired by [RestApiTutorial.com](http://www.restapitutorial.com)
Inspired by [Swagger.io](http://swagger.io/specification)
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