NOTE: This will be updated at any time.
REST(RESTfull) API Design
Protocol: HTTPS
Character Code: UTF-8
Format: JSON
Path:
If there are several words necessary in one path, use hyphen. (e.g. /users/001/profile-image)
This is because hyphen can be used in URI.
Header:
- Content-Type
application/json;charset=UTF-8
other headers, for example,
- API Key (If necessary)
do not use x- like x-api-key .
API URL:
https://api.<domain>/v1/xxxor ahttps://<domain>/api/v1/xxx
API Method Design (CRUD Operation)
The basic rule is the below.
Method: Status Code(Not Error) [Description]
GET: 200 [Get resource]
POST: 201 [Create a new resource. When there has not been a specific ID.] POST returns the resource and add the link to the resource into Location header.
PATCH: 200 [Update resource partly. When there is a specific ID.]
PATCH returns the resource.
※ 204 might be fine when the resource is not returned.
PUT: 200(Replacement), 201(New Creation) [This is used when a specific ID already exists. Replacement of the resource or create a new resource(for example, when the resource has been deleted such as file update.).]
PUT returns the resource.
※ 204 might be fine when the resource is not returned.
DELETE: 204 [Delete a resource]
Non-CRUD Operations
Like “Exploration”, REST is not the best solution. Use Verb type in this case.
例. GET /search/code?q=:query:, Github Issue Lock
It looks like the out of scope but the most important thing is whether it is understandable for Developers.
Request Body, Response Body
- JSON format
- Snake case would be better in JSON object keys. (For instance, Swagger, GitHub API use this case.)
However, if a different case is already used such as the Camel case, it would be good to unify. Coding the transformation between these cases might be necessary.
Error
Status Code
400, 401, 403, 404, 408, 422, 429, 500, 502, 504, …etc.
Response Body Example
{
"errors": [ // Array type might be good to return several errors at the same time.
{
"message": "Bad Request1",
"code": "400-001" // Sequential number(`-001`) might be good.
},
{
"message": "Bad Request2",
"code": "400-002"
},
]
}