REST API Design Guide

Common Guideline

• Use only JSON(application/json) for both for input and output body.
• Use HTTPS not HTTP.
• Prefer query parameters or template parameters and do NOT use matrix parameters or header parameters as possible.
• Avoid find all API
• Use only English for descriptions

References

• Representational state transfer (on Wikipedia)
• Google Cloud APIs API Design Guide
• Microsoft REST API Guidelines
• Kubernetes API Conventions
• Best Practices for Designing a Pragmatic RESTful API
• Understanding REST Parameters

• REST API Syntax

• HTTP Flow
• HTTP Messages
• HTTP (on Wikipedia)
• List of HTTP Header Fields
• List of HTTP Status Codes

Best Practices

• Gmail API Reference
• Twitter REST APIs
• Instagram APIs
• GitHub API v3

Common Concepts

Date, Time, Interval, Duration

• ISO 8601
• Joda-Time Key Concepts

• SQL-99 Temporal Values

  Concept	Description	Remarks
  Datetime	Represents general exact full temporal point. Generally resolves from year upto second corresponding to ‘yyyy-MM-dd HH:mm:ss’ format. Alias : Timestamp
  Date	Represents date only part. Generally resolves from year upto day corresponding to ‘yyyy-MM-dd’ format
  Time	Represents time only part. Generally resolves from hour upto second corresponding to ‘HH:mm:ss’ format.
  Interval	Represents the intervening time between two temporal points. Includes explicit start point and/or end point. For open interval, one point can be excluded. Corresponds to ‘yyyy-MM-dd HH:mm:ss ~ yyyy-MM-dd HH:mm:ss’ format.	ISO 8601 / Time Intervals
  Duration	Represents the amount of intervening time in a temporal interval.	ISO 8601 / Durations

State or Status

• ‘State’ and ‘Status’ is very similar and it is meaningless trying to distinguish them.
• Just select one.

Domain Modeling

• Clarity over Flexibility

• Resources Relationship
  • Relationship type
    • Mapping over Hierarchy
  • Fundamental resources vs Complex resources :
    • User, Product
    • Sales, Order
  • Relationship representation
    • By path : /users/{userId}/orders
    • By parameter : /orders?userId={userId}
  • 1:0…1 Separation
• Authentication and Authorization
  • Role over Privilege
• Avoid too general resource names
  • elements, entries, items
  • instances, objects, resources
  • types, values

Naming Convention

Common Abbreviation

Header

• List of HTTP header fields

Custom Request Header

Custom Response Header

• Twitter API Rate Limits
• GitHub API Rate Limiting

Response Code

Successful Response

• 200/OK

  • The information returned with the response is dependent on the method used in the request, for example:

    Method	Return
    GET	an entity corresponding to the requested resource is sent in the response
    HEAD	the entity-header fields corresponding to the requested resource are sent in the response without any message-body
    POST	an entity describing or containing the result of the action
    TRACE	an entity containing the request message as received by the end server.

• 201/Created
  • The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. The origin server MUST create the resource before returning the 201 status code. If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted)
  • A 201 response MAY contain an ETag response header field indicating the current value of the entity tag for the requested variant just created response instead.
• 202/Accepted
  • The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
  • The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent’s connection to the server persist until the process is completed. The entity returned with this response SHOULD include an indication of the request’s current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.
• 204/No Content
  • The response MAY include new or updated metainformation in the form of entity-headers, which if present SHOULD be associated with the requested variant.
  • If the client is a user agent, it SHOULD NOT change its document view from that which caused the request to be sent.
  • This response is primarily intended to allow input for actions to take place without causing a change to the user agent’s active document view, although any new or updated metainformation SHOULD be applied to the document currently in the user agent’s active view.
  • The 204 response MUST NOT include a message-body, and thus is always terminated by the first empty line after the header fields

Error Response

• List of HTTP status codes
• Twitter API Error Codes & Responses
• GitHub API Client Errors

Consideration

• What is the optimized flow of processing ?
• What if the client requested with media types other than ‘application/json’ ?
• What if the normal user try to access other user’s data ?
• Is it possible to provide intenationalized error message for errors automatically processed by framework

Pattern, Best Practice

• (List Pagination)[https://cloud.google.com/apis/design/design_patterns#list_pagination]

Common Path Word And Query Parameter

Pagination

• Listing API should always be paginated.

• Parameters :

  Parameter	Description	Datatype	Value Space	Remarks
  pageSize	page size	integer	non-negative	0 : the server or application default size
  pageNo	page position	integer	-1 or positive	1 : first page, -1 : last page

Base API

Complex Resources Hierarchy

GitHub API Style

Standard

HTTP Method Summary

Examples

Well-Known Examples

Service Program Example

Block Explorer Example

Community Example

POST /circles user

PUT /circles/{circleId} user

POST /circles/{circleId}/invitations user

GET /circles/_/invitations/belongTo/{userId} admin

PUT /circles/_/invitations/{invitationId}/deny

PUT /circles/_/invitations/{invitationId}/accept

POST /circles/{circleId}/memebers

PUT /circles/{circleId}/memebers/{userId}

PUT /circles/belongsTo/{userId}?start={start}&end={end}&pageNo={pageNo}&pageSize={pageSize}

GET /activities/{activityId} admin

GET /activities/count admin

GET /activities?userId={userId}&type={type}&start={start}&end={end}&pageNo={pageNo}&pageSize={pageSize} admin

GET /activites/recent admin

POST /activities admin

PUT /activities/{activityId} admin

GET /activities/mine/{activityId} user

GET /activities/mine/count user

GET /activities/mine?type={type}&start={start}&end={end}&pageNo={pageNo}&pageSize={pageSize} user

GET /activities/mine/recent user

Donation Token Example

Address aware style

Address unaware/corse grained style

Address unaware/fine grained style

User Service Example

{
   "swagger": "2.0",
   "info": {
      "title": "API for authentication and authorization",
      "description": "The is a API service to manage users, organizations and their authentications and authorizations",
      "contact": {
         "name": "Sangmoon Oh",
         "email": "halfface@chollian.net"
      },
      "version": "0.7"
   },
   "basePath": "/roll/v1",
   "schemas": [
      "https"
   ],
   "consumes": [
      "application/json"
   ],
   "produces": [
      "application/json"
   ],
   "paths": {
      "/users": {
         "post": {
            "description": "Adds a new user",
            "parameters": {
               "name": "user",
               "in": "body",
               "description": "the user to add",
               "schema": {
                  "$ref": "#/definitions/user"
               }
            },
            "responses": {
               "204": {
                  "description": "a user successfully added"
               }
            }
         },
         "get": {
            "description": "Lists all users including invalid users",
            "responses": {
               "200": {
                  "description": "list of all users",
                  "schema": {
                     "$schema": "http://json-schema.org/draft-04/schema#",
                     "type": "array",
                     "items": {
                        "$ref": "#/definitions/user"
                     }
                  }
               }
            }
         }
      },
      "/users/valid": {
         "get": {
            "description": "Lists all valid users",
            "responses": {
               "200": {
                  "description": "list of all valid users",
                  "schema": {
                     "type": "array",
                     "items": {
                        "$ref": "#/definitions/user"
                     }
                  }
               }
            }
         }
      },
      "/users/invalid": {
         "get": {
            "description": "Lists all invalid users",
            "responses": {
               "200": {
                  "description": "list of all invalid users",
                  "schema": {
                     "type": "array",
                     "items": {
                        "$ref": "#/definitions/user"
                     }
                  }
               }
            }
         }
      }
   },
   "defintions": {
      "user": {
         "type": "object",
         "required": [
            "id",
            "name"
         ],
         "properties": {
            "id": {
               "description": "unique identifier of the user",
               "type": "string"
            },
            "name": {
               "description": "name of the user",
               "type": "string",
               "maxLength": 256
            },
            "isValid": {
               "description": "whether this user is valid and approved to access the system or not",
               "type": "boolean",
               "default": false
            },
            "passwordExpired": {
               "description": "whether or not the password of this user is expired and so the password rest is necessary",
               "type": "boolean",
               "default": false
            },
            "registeredAt": {
               "description": "the date-time when the user is registered - the value is in UTC00:00 or ",
               "type": "string",
               "format": "date-time",
               "pattern": "[0-9]{4}-[0-1][0-9]-[0-3][0-9]T[0-2][0-9]:[0-5][0-9]:[0-5][0-9]Z"
            },
            "expireAt": {
               "description": "the date-time when the user will be expired",
               "type": "string",
               "format": "date-time"
            },
            "email": {
               "description": "most favorite email address of the user",
               "type": "string",
               "format": "email"
            },
            "extraEmails": {
               "description": "extra email addresses of the user",
               "type": "array",
               "items": {
                  "type": "string",
                  "format": "email"
               }
            },
            "emailValidations": {
               "description": "email validation history of the user"
            },
            "phoneNumber": {
               "type": "string"
            },
            "extraPhoneNumbers": {
               "type": "array",
               "items": {
                  "type": "string"
               }
            },
            "phoneNumberValidations": {

            }
         }
      }
   }
}