├── README.md └── REST-API-Cheat-Sheet.md /README.md: -------------------------------------------------------------------------------- 1 | REST API Design Cheat Sheet 2 | ================= 3 | 4 | Now! All the contents are from the book "REST API Design Rulebook" . 5 | All rights reserved by the author and publisher 6 | 7 | Please feel free to share your experience in REST API Design ,just fork the repo and send the pull request. -------------------------------------------------------------------------------- /REST-API-Cheat-Sheet.md: -------------------------------------------------------------------------------- 1 | # REST API Design Cheat Sheet 2 | 3 | ## Copyright 4 | 5 | All the contents are from the book "REST API Design Rulebook" . 6 | All rights reserved by the author and publisher 7 | 8 | ## Design Rules 9 | 10 | ### URI Format 11 | 12 | * Forward slash separator (/) must be used to indicate a hierarchical relationship 13 | * A trailing forward slash (/) should not be included in URIs 14 | * Hyphens (-) should be used to improve the readability of URIs 15 | * Underscores (_) should not be used in URIs 16 | * Lowercase letters should be preferred in URI paths 17 | * File extensions should not be included in URIs 18 | ### URI Authority Design 19 | * Consistent subdomain names should be used for your APIs 20 | * Consistent subdomain names should be used for your client developer portal 21 | ### URI Path Design 22 | * A singular noun should be used for document names 23 | * A plural noun should be used for collection names 24 | * A plural noun should be used for store names 25 | * A verb or verb phrase should be used for controller names 26 | * Variable path segments may be substituted with identity-based values 27 | * CRUD function names should not be used in URIs 28 | ### URI Query Design 29 | * The query component of a URI may be used to filter collections or stores 30 | * The query component of a URI should be used to paginate collection or store results 31 | ### Request Methods 32 | * GET and POST must not be used to tunnel other request methods 33 | * GET must be used to retrieve a representation of a resource 34 | * HEAD should be used to retrieve response headers 35 | * PUT must be used to both insert and update a stored resource 36 | * PUT must be used to update mutable resources 37 | * POST must be used to create a new resource in a collection 38 | * POST must be used to execute controllers 39 | * DELETE must be used to remove a resource from its parent 40 | * OPTIONS should be used to retrieve metadata that describes a resource’s available interactions 41 | ### Response Status Codes 42 | * 200 (“OK”) should be used to indicate nonspecific success 43 | * 200 (“OK”) must not be used to communicate errors in the response body 44 | * 201 (“Created”) must be used to indicate successful resource creation 45 | * 202 (“Accepted”) must be used to indicate successful start of an asynchronous action 46 | * 204 (“No Content”) should be used when the response body is intentionally empty 47 | * 301 (“Moved Permanently”) should be used to relocate resources 48 | * 302 (“Found”) should not be used 49 | * 303 (“See Other”) should be used to refer the client to a different URI 50 | * 304 (“Not Modified”) should be used to preserve bandwidth 51 | * 307 (“Temporary Redirect”) should be used to tell clients to resubmit the request to another URI 52 | * 400 (“Bad Request”) may be used to indicate nonspecific failure 53 | * 401 (“Unauthorized”) must be used when there is a problem with the client’s credentials 54 | * 403 (“Forbidden”) should be used to forbid access regardless of authorization state 55 | * 404 (“Not Found”) must be used when a client’s URI cannot be mapped to a resource 56 | * 405 (“Method Not Allowed”) must be used when the HTTP method is not supported 57 | * 406 (“Not Acceptable”) must be used when the requested media type cannot be served 58 | * 409 (“Conflict”) should be used to indicate a violation of resource state 59 | * 412 (“Precondition Failed”) should be used to support conditional operations 60 | * 415 (“Unsupported Media Type”) must be used when the media type of a request’s payload cannot be processed 61 | * 500 (“Internal Server Error”) should be used to indicate API malfunction 62 | ### HTTP Headers 63 | * Content-Type must be used 64 | * Content-Length should be used 65 | * Last-Modified should be used in responses 66 | * ETag should be used in responses 67 | * Stores must support conditional PUT requests 68 | * Location must be used to specify the URI of a newly created resource 69 | * Cache-Control, Expires, and Date response headers should be used to encourage caching 70 | * Cache-Control, Expires, and Pragma response headers may be used to discourage caching 71 | * Caching should be encouraged 72 | * Expiration caching headers should be used with 200 (“OK”) responses 73 | * Expiration caching headers may optionally be used with 3xx and 4xx responses 74 | * Custom HTTP headers must not be used to change the behavior of HTTP methods 75 | ### Media Type Design 76 | * Application-specific media types should be used 77 | * Media type negotiation should be supported when multiple representations are available 78 | * Media type selection using a query parameter may be supported 79 | ### Message Body Format 80 | * JSON should be supported for resource representation 81 | * JSON must be well-formed 82 | * XML and other formats may optionally be used for resource representation 83 | * Additional envelopes must not be created 84 | ### Hypermedia Representation 85 | * A consistent form should be used to represent links 86 | * A consistent form should be used to represent link relations 87 | * A consistent form should be used to advertise links 88 | * A self link should be included in response message body representations 89 | * Minimize the number of advertised “entry point” API URIs 90 | * Links should be used to advertise a resource’s available actions in a state-sensitive manner 91 | ### Media Type Representation 92 | * A consistent form should be used to represent media type formats 93 | * A consistent form should be used to represent media type schemas 94 | ### Error Representation 95 | * A consistent form should be used to represent errors 96 | * A consistent form should be used to represent error responses 97 | * Consistent error types should be used for common error conditions 98 | ### Versioning 99 | * New URIs should be used to introduce new concepts 100 | * Schemas should be used to manage representational form versions 101 | * Entity tags should be used to manage representational state versions 102 | ### Security 103 | * OAuth may be used to protect resources 104 | * API management solutions may be used to protect resources 105 | ### Response Representation Composition 106 | * The query component of a URI should be used to support partial responses 107 | * The query component of a URI should be used to embed linked resources 108 | ### JavaScript Clients 109 | * JSONP should be supported to provide multi-origin read access from JavaScript 110 | * CORS should be supported to provide multi-origin read/write access from JavaScript 111 | 112 | 113 | --------------------------------------------------------------------------------