Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

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

SnapLogic is the leading self-service enterprise-grade integration platform. Download the 2018 GartnerMagic Quadrant for Enterprise iPaaS or play around on the platform, risk free, for 30 days.

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

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.

With SnapLogic’s integration platform you can save millions of dollars, increase integrator productivity by 5X, and reduce integration time to value by 90%. Sign up for our risk-free 30-day trial!

Topics:
integration ,rest api ,api design

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}