RestAPIs

RestAPIs

1. URI Format

   • URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
   • Rules
     • Forward slash separator (/) must be used to indicate a hierarchical relationship
     • A trailing forward slash (/) should not be included in URIs
     • Hyphens (-) should be used to improve the readability of URIs
     • Underscores (_) should not be used in URIs
     • Lowercase letters should be preferred in URI paths
     • File extensions should not be included in URIs

2. Resource Archetypes

   • Document
     • a singular concept that is akin to an object instance or database record
   • Collection
     • a server-managed directory of resources.
   • Store
     • lets an API client put resources in, get them back out, and decide when to delete them
     • stores do not create new resources; therefore a store never generates new URIs. 
   • Controller
     • are like executable functions, with parameters and return values; inputs and outputs

3. URI Path Design

   • A singular noun should be used for document names
   • A plural noun should be used for collection names
   • A plural noun should be used for store names
   • A verb or verb phrase should be used for controller names
   • Variable path segments may be substituted with identity-based values
   • CRUD function names should not be used in URIs

4. URI Query Design

   • The query component of a URI may be used to filter collections or stores
   • The query component of a URI should be used to paginate collection or store results

5. Request Methods

   • Rules
     • GET and POST must not be used to tunnel other request methods
     • GET must be used to retrieve a representation of a resource
     • HEAD should be used to retrieve response headers
     • PUT must be used to both insert and update a stored resource
       • PUT must be used to update mutable resources
     • POST must be used to create a new resource in a collection
     • POST must be used to execute controllers
     • DELETE must be used to remove a resource from its parent
     • OPTIONS should be used to retrieve metadata that describes a resource’s available interactions

6. Response Status Codes

   • Rules
     • 200 (“OK”) should be used to indicate nonspecific success
       • 200 (“OK”) must not be used to communicate errors in the response body
     • 201 (“Created”) must be used to indicate successful resource creation
     • 202 (“Accepted”) must be used to indicate successful start of an asynchronous action
     • 204 (“No Content”) should be used when the response body is intentionally empty
     • 301 (“Moved Permanently”) should be used to relocate resources
     • 302 (“Found”) should not be used
     • 303 (“See Other”) should be used to refer the client to a different URI