Skip to content
This repository was archived by the owner on Apr 17, 2019. It is now read-only.

api definition rules.md

Jump to bottom
lang edited this page Mar 5, 2015 · 1 revision

Overview

This part of APIs are expected to be used by client side JS AJAX callings, even by other client side tools later. These APIs will be defined in high level view point, and will not touch the low level data collections and processing.

All the APIs are defined as RESTful web services, with some exceptional cases as less as possible. And all the response data will be pure json.

The definition for each API will cover the following factors:

  • Input

    • URL, as the resource locator
    • Method
    • Request headers
    • Extra query params in URL
    • Payload data (in json) as POST/PUT requests
    • User authentication requirement

  • Expected Output

    • Status code
    • Response headers
    • json response schema

All About REST API

Basic

  • Resources
  • URI as the unique resource locator
  • HTTP methods: GET/POST/PUT/DELETE for CRUD operations
  • Stateless nature of http

Types of Resources

  • Document
  • Collection
  • Store
  • Action - for non-CRUD operations

Rules of RESTful API Definition

  • URIs

    • "/" must be used to indicate a hierarchical relationship
    • Trailing "/" should not in URI
    • "-" may be used for readability of URIs
    • "_" should be used in URIs
    • All lowercase letters in URIs
    • No file extentions

  • Resource name

    • A singular noun for 'Document'
    • A plural noun for 'Collection'
    • A plural noun for 'Store'
    • A verb or verb phrase for 'Action' name
    • Variable path segments may be substituted with identify-based values
    • CRUD function names should be in URIs

  • Query parameters

    • Can be used to filter Collection or Store
    • Can be used to paginate Collection or Store result

Matrix of HTTP Method and Resource Type

     | Document      | Collection | Store    | Action

GET | Read single | Read all | Read all | X POST | X | Create new | X | Excute PUT | Update single | Update all | X | X DELETE | Delete single | Delete all | Clean up | X

HTTP status code

  • 200 - OK

  • 201 - Created

  • 202 - Accepted (async task)

  • 204 - No content

  • 301 - Move permanently

  • 303 - See other

  • 304 - Not modified

  • 307 - Temp redirect

  • 400 - Bad request

  • 401 - Unauthorized

  • 402 - Forbidden

  • 404 - Not found

  • 405 - Method not allowed

  • 406 - Not acceptable

  • 409 - Conflict

  • 412 - Precondition failed

  • 415 - Unsupported media type

  • 500 - Internal server error

HTTP response headers

  • "Content-Type" - media type of entity body
  • "Content-Length" - size of entity body
  • "Last-Modified" - date-time of last significant state change
  • "Cache-Control" - TTL-based caching value (seconds)
  • "ETag" - Indicates the version of response msg entity
  • "Location" - URI of resource
Clone this wiki locally