restful
why:
- meaningful
This will be improve efficiency , less documents , just read the code - auto generate support
Resource can be achieve automatically without writing any code according to the data model or (java) repository - DRY
It becomes unnecessary to think about what's good web url for providing api to the client developer --- Just following the standard
related resource
example get the portfolios of 90 days of use id 123 :
also another :
use standard http status code
standard without extra documents, we should return http status code according to the standard
useful http status code we should know:
- 200 OK : response for GET PUT DELETE request .
- 201 Created
- 304 Not Modified
- 302 Found : Redirect
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden : logged in user, but not allow to access the resource
- 405 Method Not Allowed: usually for POST/PUT/DELETE request but is now request by GET request
- 429 Too Many Request: for rate limit
401 403 405 are usually used right
when a POST request post succeed, but no new result generated, we should return 200 , instead of 201
security
- with authentication :
Many of the request should first logged in to get the access token in order to have the permission to access resources. Usually we have several simple ways to carry the token in the request body :- within the http header
- within the cookies
- within the url : http://www.example.com/user/123?token=a12dc5
- with hash
Another way to keep the web request safe is to use hash code the encrypt the web parameters , example: http://www.example.com/user/123/order/541?amount=100&product=wade&hash=d328af;
hash the parameters : amount=100&product=wade
besides , usually the parameters is sorted by alphabet
To avoid middle man problem, we should use https.
standard Oauth 2.0 example
prosper oauth flow
simple we should do :
- register to get client id and client secrect
- app granted by the user to get a auth_key according to user's grant permission
- now we can access the api via the access token and refresh token, both of which get an expire time
- if token has expired , we need to re-access the api
request example:
POST <prosper_base_address>/security/oauth/token
Accept: application/json
Content-type: application/x-www-form-urlencoded
grant_type=refresh_token&client_id=<your_client_id>&client_secret=<your_client_secret>&refresh_token=<existing_refresh_token_from_user_token_request>
response example:
{
"access_token": "5098afd7-f216",
"token_type": "bearer",
"refresh_token": "7fcb8a8a-e7dd",
"expires_in": 3599
}
Note that:
error standard
some use direct HTTP STATUS CODE , ref to session: ### use standard http status code
- method 1
http status code 401
{
error: "Invalid API key"
}
- method 2:
should support http status code 、error code 、error msg
example with a 200 OK:
{
"code": -1,
"message": "Something gone wrong",
<!-- "description": "optional print your stack message here" --> //this is optional , usally for error stack message
}
dig into well know company api example
mouseflow
update a new website
PUT /websites/{website-id}
curl -X PUT -u my@email.com:token1234 -d '{"name": "myshop2.com", "recordingRate": 2}' https://api-us.mouseflow.com/websites/{website-id}
simple prosper api
https://developers.prosper.com/docs/investor/accounts-api/
Authorization is in header -- which help us to which one is operating user
Version
There way to represent version:
-
/api/v1/user
-
/api/user?version=v1
-
/api/user with req.header set
version=v1
/api/v1/user is better for Load balancer to reganize
And /api/v1/user is better for rest api rather than /api/user?version=v1 , which will be use as a query:
version=v1
At last /api/v1/user is simpler compare with set to req.header
ref
RESTful API 设计指南
best practices for a pragmatic restful api
API 杂谈
rest api design
best api design
auth api design sample