Common Mistakes in REST API Design
Designing and developing a REST API is tricky business. Read on for some common pitfalls you should make sure to avoid during the design process.
Join the DZone community and get the full member experience.
Join For FreeI was thinking API design is pretty easy and intuitive. But actually, it's not.
Just like the famous difficulty of naming things (functions, variables, modules), designing a clean and just-enough API takes experience and effort.
Good Examples/Resources:
- Examples: GitHub API, DigitalOcean API
- API Framework: Swagger, Postman
- Debuging REST API: SoapUI, fiddler, curl
- HTTP response status codes
- Designing a RESTful API with Python and Flask
Common Mistakes
- In GET requests, add parameters inside the body, instead of in a URL.
- Use lengthy names, while we have better choices
project_id -> id
project_name -> name
err_msg -> message
Define our own error code and error message. Try to reuse the HTTP protocol first.
curl -i https://api.github.com -u foo:bar
HTTP/1.1 401 Unauthorized
{
"message": "Bad credentials",
"documentation_url": "https://developer.github.com/v3"
}
curl -i https://api.github.com -u valid_username:valid_password
HTTP/1.1 403 Forbidden
{
"message": "Maximum number of login attempts exceeded. Please try again later.",
"documentation_url": "https://developer.github.com/v3"
}
Better use a dash(-), instead of an underline("_").
From:
http://api.dennyzhang.com/books/my_first_post
To:
http://api.dennyzhang.com/books/my-first-post
Missing API protocol versions in the URL. It would be hard to manage, when we have API breaking changes.
From:
> GET /projects
To:
> GET /v1/projects
NO authentication to protect our system from malicious requests.
See example from GitHub.
There are three ways to authenticate through REST API.
Requests that require authentication will return 404 Not Found, instead of 403 Forbidden.
This is to prevent the accidental leakage of private repositories to unauthorized users.
1. Basic authentication
curl -u "username" https://api.github.com
2. OAuth2 token (sent in a header)
curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com
3. OAuth2 token (sent as a parameter)
curl https://api.github.com/?access_token=OAUTH-TOKEN
- Unnecessary or useless parameters in the BODY of request or response.
- Make sure the APIs are logically correct.
- Remember to support pagination, if too much data isinvolved.
GET /v1/projects?page=${page}&per_page=${per_page}
# page: page numbering is 1-based
# per_page: How many bid counts we want to see for each page
Sorted in ascending order.
The default is 30. The valid range is [1, 400] (inclusive)
HTTP/1.1 200 OK
{
"count": 2,
"projects":[
{
"id": int,
"summary": string,
"description": string
},
{
"id": int,
"summary": string,
"description": string
}
]
}
The response is a JSON file with an embedded list. Make sure it's valid JSON.
HTTP/1.1 200 OK
{
"project_id": int,
"name": string,
"description": string,
"budget": float,
"deadline": timestamp,
"item_list": [
id1: int,
id2: int,
id3: int
]
}
Sample:
startMachine
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" \
-d '{"type":"reboot"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"
This is how digitalocean deals with it.
Resource is actions. HTTP method is POST.
Published at DZone with permission of Denny Zhang, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.
Comments