Guidelines for RESTful Interface
Introduction
This is a guidelines for RESTful applications.
Method
[Using HTTP Methods for RESTful Services]
| Method | Meaning |
|---|---|
| POST | Create |
| GET | Read |
| PUT | Update/Replace |
| DELETE | Delete |
Exceptions and Error Codes
-
Code: 200 - OK
For good return. -
Code: 401 - Unauthorized
If the user is not login or session expired. -
Code: 402 - Payment Required
For payment operations if the user has not paid it. -
Code: 403 - Forbidden
Use it when the user does not have permission to run the operation. -
Code: 404 - Not Found
For get method, when the specific resource is not found. -
Code: 409 - Conflict if the resource already exists
For create operation, when there is a conflict for unique keys. -
Code: 500 - Internal Exception
For normal exceptions -
Code: 501 - Not Implemented
For not implemented operations.
URL
-
Get a resource with id
GET resources/{id} -
Get a resource with name
GET resources?name=Name -
Create a resource
POST resources
body with creating resource content
response body with created resource content. -
Update a resource
PUT resources/{id}
body with updating resource content -
Update a resource with specific field value
PUT resources/{id}?name=Name -
Delete a resource
DELETE resources/{id} -
Filter resources with simple conditions
GET resources?name=Name
GET resources?gender=woman&orderby=Name - Search resources with complex conditions
There are 2 approaches, one is using GET and another one is using POST.-
GET with a complex URL
Pure RESTful methodism like it.
GET resources?filter=[(field,operation,value),(name, like, A)] -
POST with body
POST resources/search
body with search options
-
- Action
-
Prefer to consider the action as a update first.
PUT resources/{id}?islocked=true -
Use action parameter
PUT resources/{id}?action=lock¶m=value&…
PUT resources?action=lock¶m=value&… -
Define the action like a resource.
Pure RESTful methodism does not like the method, as it is not a resource.
PUT resources/{id}/actions/lock?param=value&…
PUT resources/actions/lock?id={id}¶m=value&…
PUT resources/!/actions/lock?id={id}¶m=value&…
-
Body
- Use json as the body format.
Response Content
- Use json as the content format.