best practices for designing web api

design rest

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

example get the portfolios of 90 days of use id 123 :

http://www.example.com/user/123/portfolios/90

also another :

http://www.example.com/apidoc/201607/docid/98

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