10 advices to make good APIs

API is the communication language between systems.  Good APIs can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an impression about your product – for better or for worse.

Here’s my list of 10 of the most useful API advices for developers:


1. Request Method

  • GET: A GET request is read-only that doesn’t change thing.  For example: get a comments list of a post.
  • POST: POST is utilized to create new resources, and return a location header with a link to the newly-created resource with the 201 HTTP status. For example: create a new comment.
  • PUT: PUT is utilized for update capabilities. PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource.
  • PATCH: Patch request says that we would only send the data that we need to modify without modifying or effecting other parts of the data.
  • DELETE: DELETE is pretty easy to understand. It is used to delete a resource identified by a URI.

PUT or POST:  PUT-ing is idempotent, but POST-ing is not. Idempotent is a fancy word for “can do it over and over again without causing different results”.

2. Accept serialized JSON in request bodies

GET query data and POST form is commonly in tiny data, but it is not convenient  to deal with a propertied object. JSON object is more commonly to post data. e.g.

$ curl -X POST https://service.com/apps
-H “Content-Type: application/json”
-d ‘{“name”: “demoapp”}’
“id”: “01234567-89ab-cdef-0123-456789abcdef”,
“name”: “demoapp”,
“owner”: {
“email”: “username@example.com”,
“id”: “01234567-89ab-cdef-0123-456789abcdef”


3. Use the plural for resource names

Use the plural version of a resource name unless the resource in question is a singleton within the system.

4. URL rules

Downcase paths and attributes, e.g.


it may be inconvenient for end-users to provide IDs to identify a resource. e.g.


5. Minimize path nesting

In data models with nested parent/child resource relationships, paths may become deeply nested, e.g.:


For the case above where a dyno belongs to an app belongs to an org:


6. Prefer short and clearly endpoint name

Prefer endpoint configurations that don’t require special actions.  simply like:


In case the actions is needed, clearly delineate them with the actions prefix:


And a top-level actions delineation is useful for actions on collections.



7. Status codes

Try to use HTTP status codes in a REST service.

  • 1xx (Informational): The request was received, continuing process
  • 2xx (Successful): The request was successfully received, understood, and accepted
  • 3xx (Redirection): Further action needs to be taken in order to
    complete the request
  • 4xx (Client Error): The request contains bad syntax or cannot be
  • 5xx (Server Error): The server failed to fulfill an apparently
    valid request

Refer to the HTTP protocol Status Code Definitions spec for guidance on status codes for user error and server error cases.

8. Provide resource (UU)IDs

Auto increment ID is devil for safety, it means people can download your database with a simple traverse function.

9. Nest foreign key relations

Two ways are suggested to complex object:

Linked foreign objects, e.g.

   "posts": [{
      "id": "1",
      "title": "Awesome API Advise",
     "_links": {
       "comments": ["1", "2"]
     }, {
     "id": "2",
     "title": "We are expecting more",
     "_links": {
       "comments": ["3"]
   "_linked": {
     "comments": [
         "id": "1"
         "message": "Great post",
         "created_at": "2018-08-23T18:20:03Z"
         "id": "2"
         "message": "I loved",
         "created_at": "2018-08-24T20:04:01Z"
         "id": "3"
         "message": "Ugh JSON-API...",
         "created_at": "2018-08-29T14:01:13Z"

Linked foreign objects will avoid duplicating the same item multiple times. While a comment would likely only be on a single post, if you were to include user information, the same user could show up multiple times as a commenter if they are active, or even as a commenter and a post author.

Embedded documents, e.g.

     "data": [
             "id": 2,
              "name": "Videology",
              "lat": 40.713857,7             "lon": -73.961936,
              "created_at": "2013-04-02",
              "checkins" : [
                 // ...
             "merchant" : {
                 // ...
             "id": 1,
             "name": "Barcade",
             "lat": 40.712017,
             "lon": -73.950995,
             "created_at": "2012-09-23",
             "checkins" : [
                 // ...
             "merchant" : {
                 // ...


10.Provide human-readable docs

Use prmd docs and API blueprint  to create a readable docs.



  1. HTTP API Design Guide
  2. Build APIs You Won’t Hate By Phil Sturgeon