Common Mistakes in REST API Design

DZone 's Guide to

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.

· Integration Zone ·
Free Resource

I 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:

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("_").


  • Missing API protocol versions in the URL. It would be hard to manage, when we have API breaking changes. 

> GET /projects

> 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,
      "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.
api design, integration, rest api

Published at DZone with permission of Denny Zhang , DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}