NEEDS FORMATTING: Credit goes to NYU API Team found here
- Title and documentation must be defined.
- RAML file name must be different from api.raml
- Use RAML version 1.0
Base URL & Versioning Include the “api” word and the version of the API in the base Url (e.g. domain/api/v1) Fields Use lower camelCase, preferable not underscores (e.g.: lastName) Use snake_case (e.g: last_name) Define a transaction_id/caller_id header to track the requests (optional) Date Time Representations Use UTC ISO8601 Use standard date formats 2018-01-02T13:42:21+00:00 (+00:00 is the time zones hour offset) 2018-01-02T13:42:21Z (Z is place holder for local time zone) Methods GET, POST, PUT, DELETE Should be used following the right verb logic GET: For obtaining data. PUT (Idempotent): To update data. It will update the entire instance. PATCH: To update data. It will update partial data of an instance. POST (Not idempotent): To store data. DELETE: To delete an instance. Version Has to be defined (v1,1.0) for the resources. Resources Under each resource, all fields should be written using lower camelCase Resources Use nouns, not verbs, lower case. Example: /users, /accounts Coarse grained, not fine grained For resources with more than 2 words use lowercase for both words (example: /lineitems) or use kebab-case (aka spinal-case) (example: /line-items) Error codes defined in each resource-method pair Query Parameters Use snake_case (example: date_from, date_to) When dealing with collections, use comma separated values, e.g. /users?fields=name,last_name Media Types For the request: use ‘Accept’ header For the response: use ‘Content-Type’ Resource Types Collection resource /users Instance resource /users/{id} (example: /users/123 ) Schemas, Data Types Separate the schemas and data types from the base RAML file. Externalize them in a separate file. Should contains valid – mocked data Examples Always include examples Separate the examples from the base RAML file. Externalize them in a separate file. Should contains valid – mocked data Traits Use traits to define common method properties such as query-parameters and responses. Separate the traits from the base RAML file. Externalize them in a separate file. Security Security traits defined Confidential data should be obfuscated / avoided in examples, query parameters, etc. Pagination When dealing with large responses, force pagination to avoid performance issues (long response times), define the offset and limit. Discoverability API Fragments Common data types, traits, resource types, schemas, examples, must be externalized as API Fragments in Exchange to promote reusability in API Design. Schemas/Examples/DataTypes defined for each resource Response Codes HTTP status codes are grouped into five numeric categories:
CODE
TYPE
1xx informational 2xx successful 3xx redirection 4xx client error 5xx server error These response codes should be used as standard, the use of not defined return codes is discouraged and should only be done in exceptional circumstances.
CODE
HTTP METHOD
RESPONSE BODY
DESCRIPTION
200 OK GET, PUT, DELETE Resource There are no errors, the request has been successful 201 Created POST URI of the resource that has been created The request has been fulfilled and resulted in a new resource being created 202 Accepted POST, PUT, DELETE An URI of a resource which represents the processing status The request has been accepted for processing, but the processing has not been completed 204 No Content GET, PUT, DELETE N/A There are no errors, the request has been processed and no contact is expected in the body (by design) 400 Bad request GET, POST, PUT, DELETE Error message The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications 401 Unauthorized GET, POST, PUT, DELETE Error message The request requires user authentication 404 Not Found GET, POST, PUT, DELETE Error message The server has not found anything matching the request URI 405 Method Not Allowed GET, POST, PUT, DELETE Error message The method specified in the request is not allowed for the resource identified by the URI 406 Not Acceptable GET, POST, PUT, DELETE Error message The request contains parameters that are not acceptable 415 Unsupported Media Type GET, POST, PUT Error Message The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method 500 Internal Server Error GET, POST, PUT, DELETE Error message The server encountered an unexpected condition which prevented it from fulfilling the request