- Use the Internet - The web brings a lot of tools to the table, make sure and learn about existing web technologies, and put them to use across the API design process.
- Simplicity - Consider simplicity at ever turn when designing APIs, providing the small possible unit of value you possibly can--simplicity goes a long way.
- Consistency - Employ consistent approaches to all aspects of API design, providing a familiar approach across all APIs published.
- Easy to Read - While APIs are for computers, they should be easy to read by humans, making documentation more accessible.
- Easy to Learn - Keeping APIs simple, and consistent, will contribute to them being easy to learn about for any potential API consumer.
- Hard to Misuse - When APIs do one thing, and does it well, you reduce the opportunity for misuse, and people putting them to work in unintended ways.
- Audience Focused - APIs should be designed with a specific audience in mind, providing a solution to a problem they are having.
- Experience Over Resource - Make APIs reflect how they will be used, and experienced, over where the API came from and the resource it was derived from.
- Naming - How to name things
- Case - Which case (lowercase, camelCase, ...) to use and when
- Global design - General considerations on API design
- Use Your Own APIs - Always use your own APIs, allowing you to understand the challenges with integrating, as well as the pain of operations and outages.
- Notifying API consumers - How to send events or notifications to API consumers
- HTTP Headers - The usage of standard or custom HTTP headers
- SSL - Transport Layer Security (TLS) and its predecessor, Secure Sockets Layer (SSL), both of which are frequently referred to as SSL, are cryptographic protocols designed to provide communications security over a computer network. Always support TLS / SSL by default when it comes to API operations, if at all possible.
- Host - Put sufficient thought into what the baseURL will be for making API calls. Increasingly this element can also be dynamic, like other aspects of API design.
- Resource - Consider how you craft your resources across all API operations. I do not subscribe to specific philosophies around this, just trying to provide a framework to think about this in.
- Action - Allow for standard actions to be taken across resource, but also reflect how APIs will be experienced, providing meaningful action to be taken around any API.
- Verbs - Learn about, and put all HTTP verbs to use when designing APIs.There is more than just GET, and even more than just POST, PUT, and DELETE.
- Parameters - Standardize how parameters are crafted as part of API operations, using intuitive and consistent approaches.
- Headers - Learn about, and use common headers for API requests. Study how the APIs you consumer put headers to work.
- Body - Use the body of each request in a consistent way across API operations. The body provides much more room for more structured data and content.
- Versioning - Establish, and stick to a common versioning strategy, and use throughout API evolutions. Consider putting all versioning information within headers.
- Pagination - Learn about common ways to paginate, and establish a single way to handle across API operations.
- Filtering - Consider how filtering will happen across all APIs, and establish a single way to filter API resources.
- Time Selection - Consider how time selection and series will be handled, and establish a single way for working with time in API operations.
- Sorting - Establish a single approach to how API responses can be sorted, and use across all API resources.
- Field Selection - Consider providing a way that API consumers can select which fields are included in API responses.
- Granularity - Always be aware of the granularity of your API endpoints, and each resource being exposed, keeping everything as small as possible.
- Relationship - Consider how relationships between resources will be handled, and establish a single approach for doing across API operations.
- GET - The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect.
- POST - The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, for example, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.
- PUT - The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.
- PATCH - The PATCH method applies partial modifications to a resource.
- DELETE - The DELETE method deletes the specified resource.
- OPTIONS - The OPTIONS method returns the HTTP methods that the server supports for the specified URL. This can be used to check the functionality of a web server by requesting ‘*’ instead of a specific resource.
- HEAD - The HEAD method asks for a response identical to that of a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content.
- Forbidden methods alternatives - What to do when only possible HTTP methods are POST and GET
- HTTP Headers - The usage of standard or custom HTTP headers
- Status Codes - Learn about, and use HTTP status codes in a consistent way across all API operations.
- Error Handling - Establish a single error handling strategy, and apply consistently across all API operations.
- Rate Limits - Establish a single approach to rate limiting of API resources, and apply consistently across all API operations.
- Caching - Learn about common approaches to caching, and make sure it is applied through API operations.
- eTags - Learn about etags are used as part of caching and operations, and employ them as part of your caching strategy, and usage of HTTP elements.
- Request-Ids - Employ Request-Ids if possible providing added details for logging, auditing, and reporting on API usage.
- UTF-8 - UTF-8 is a character encoding capable of encoding all possible characters, or code points, in Unicode. The encoding is variable-length and uses 8-bit code units. Make sure you use UTF-8 encoding for your API responses, supporting proper encoding.
- CORS - Enable CORS for your API endpoints, providing the most flexibility possible in making API calls.
- JSONP - Provide JSONP if you are unable to enable CORS, allowing for easier integrations.
- Schema - The JSON Schema, MSON, or other machine readable approach to defining the underlying data model of the API response.
- Compression - Gzip or other compression format for API responses.
- Collection - What is a collection (set) of resources
- Sorting a collection - How to sort a collection of resources
HTTP Status User Error
- 400 Bad Request - The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, too large size, invalid request message framing, or deceptive request routing).
- 401 Unauthorized - Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
- 403 Forbidden - The request was a valid request, but the server is refusing to respond to it. The user might be logged in but does not have the necessary permissions for the resource.
- 404 Not Found - The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
- 405 Method Not Allowed - A request method is not supported for the requested resource; for example, a GET request on a form which requires data to be presented via POST, or a PUT request on a read-only resource.
- 406 Not Acceptable - The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.
- 408 Request Timeout - The server timed out waiting for the request. According to HTTP specifications: The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time.
- 409 Conflict - Indicates that the request could not be processed because of conflict in the request, such as an edit conflict between multiple simultaneous updates.
- 410 Gone - Indicates that the resource requested is no longer available and will not be available again. This should be used when a resource has been intentionally removed and the resource should be purged. Upon receiving a 410 status code, the client should not request the resource in the future. Clients such as search engines should remove the resource from their indices. Most use cases do not require clients and search engines to purge the resource, and a 404 Not Found may be used instead.
- 411 Length Required - The request did not specify the length of its content, which is required by the requested resource.
- 412 Precondition Failed - The server does not meet one of the preconditions that the requester put on the request.
- 415 Unsupported Media Type - The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.
- 422 Unprocessable Entity - The request was well-formed but was unable to be followed due to semantic errors.
- 423 Locked - The resource that is being accessed is locked.
- 428 Precondition Required - The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.
- 429 Too Many Requests - The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.
HTTP Status Redirection
- 301 Moved Permanently - This and all future requests should be directed to the given URI.
- 302 Found - Common way of performing URL redirection. An HTTP response with this status code will additionally provide a URL in the location header field. The user agent (e.g. a web browser) is invited by a response with this code to make a second, otherwise identical, request to the new URL specified in the location field.
- 303 See Other - The response to the request can be found under another URI using a GET method. When received in response to a POST (or PUT/DELETE), the client should presume that the server has received the data and should issue a redirect with a separate GET message.
- 304 Not Modified - Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match. In such case, there is no need to retransmit the resource since the client still has a previously-downloaded copy.
HTTP Status Server Error
- 500 Internal Server Error - A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
- 501 Not Implemented - The server either does not recognize the request method, or it lacks the ability to fulfill the request. Usually this implies future availability (e.g., a new feature of a web-service API).
- 503 Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.
HTTP Status Success
- 200 OK - Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
- 201 Created - The request has been fulfilled, resulting in the creation of a new resource.
- 202 Accepted - The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs.
- 204 No Content - The server successfully processed the request and is not returning any content.
- 206 Partial Content - The server is delivering only part of the resource (byte serving) due to a range header sent by the client. The range header is used by HTTP clients to enable resuming of interrupted downloads, or split a download into multiple simultaneous streams.
- Error format - How to provide information about errors
- Errors - How to handle errors
- Content negociation and media types - How to describe your API data format and/or propose different formats (like json, yaml, xml atom, ...)
- application/json - Provide JSON media types for API responses.
- application/xml - Provide XML media types for API responses.
- application/csv - Provide CSV media types for API responses.
- text/html - Provide HTML media types for API responses.
- application/atom+xml - Provide ATOM media types for API responses.
- JSON Schema - JSON Schema, describes your JSON data format. JSON Hyper-Schema, turns your JSON data into hyper-text. Use JSON schema when possible to standardize and validate your JSON structure.
- iCalendar - Use iCalendar when representing date / time formats in your API responses.
- vCard - vCard is a file format standard for electronic business cards. vCards are often attached to e-mail messages, but can be exchanged in other ways, such as on the World Wide Web or instant messaging. They can contain name and address information, telephone numbers, e-mail addresses, URLs, logos, photographs, and audio clips. Use vCard when representing contact data in your API responses.
- KML - When working with mapping data, represent it using KML when possible.
- geoRSS - Also consider geoRSS when representing you geographic data.
- m3u - When providing formatted data for media formats, consider using m3u.
- UUID - Use a universally unique identifier (UUID) when possible.
- ISO 8601 (Date / Time) - ISO 8601 Data elements and interchange formats – Information interchange – Representation of dates and times is an international standard covering the exchange of date and time-related data. The purpose of this standard is to provide an unambiguous and well-defined method of representing dates and times, so as to avoid misinterpretation of numeric representations of dates and times, particularly when data are transferred between countries with different conventions for writing numeric dates and times.
- ISO 4217 (Currency) - Use ISO 427 data elements and interchange formats for the representation currency codes. ISO 4217 is a standard published by International Organization for Standardization, which delineates currency designators, country codes (alpha and numeric), and references to minor units in three tables: current currency & funds code list, current funds codes, list of codes for historic denominations of currencies & funds.
- ISO 3166 (Country) - Use ISO 3166 data elements and interchange formats for the representation country codes. The purpose of ISO 3166 is to define internationally recognized codes of letters and/or numbers that we can use when we refer to countries and subdivisions. However, it does not define the names of countries .
- RDFa - Consider using RDFa for adding rich meta data to HTML representations.
- Schema.org - Consider using Schema.org representations for common data elements.
- Markdown Syntax for Object Notation (MSON) - A Markdown syntax compatible with describing JSON and JSON Schema.
- RFC 7807 - This document defines a problem detail as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.
- Update resource - How to update a resource
- Track change - How to track change on resources
- Batch Bulk - How to handle batch/bulk processing/creation/update/... (e.g. handle multiple resources at conce)
- Update resource partially - How to udate partially a resource
- Delete resource - How to delete resources
- Retrieve resource - How to retrieve a resource
- ID with semantic - Using meaningful ids (like `me`)
- Replace resource - How to replace (or update fully) a resource
- Resource - General informations about resources
- URL format - How to design URLs
- Create resource - How to create resources
- Resource's state - How to change a resources state/status (like processed/sent/paid/...)
- Resource ID - What is a resource ID and/or how its built
- Action resource - How to use action resource (e.g. resources like /cancel or /approve)
- Create resource with a specific ID - How to create resource with a provided id
- Relationships - How to define and use relations between resources
- Retrieve resource partially - How to retrieve partially a resource
- Definitions - Usage of common API definition formats like Swagger, API Blueprint, RAML, and others for describing and defining APIs.
- Editor - An IDE for editing API definitions, as well as possible GUI interface for editing all of API details through desktop or web tooling.
- Forkable - Allow an API definition to be forked, and built upon using a common API definition format.
- Sharing - Allow for API definitions to be shared amongst team members through links, chat, email, and other channels.
- Collaboration - Enable the collaboration between users, both technical, as well as business stakeholders.
- Annotation - Provide tooling for annotating API definitions that the design it represents, leaving notes and comments at all layers.
- Translation - Allowing for the translation of API designs between common API definition formats, allowing users to speak in any format.
- Highlighting - Enable highlighting of specific aspects of an API design to differentiate it from other areas, and establishing common patterns.
- Guide - Pull together a common API design guide for use across an organization and sharing with the public to demonstrate a standard approach is being used.
- Notebook - A notebook for storing of API definitions into a single, potentially shareable location that can be used by an individual or group throughout the API lifecycle.
- Collections - A folder or collection of API definitions mean to represent a single or multiple API descriptions and definitions, for use throughout API lifecycle.
- Dictionary - A common set of API values to help provide consistent naming and patterns to be used at different layers of the API design process.
- Contact - A common approach to defining and providing relevant contact information for each API resource crafted.
- Language - Which language(s) use when designing an API
- Accept-Language - Set the language the API should be speaking using Accept-Language.
- Governance - How to ensure API governance (advertise, consistency, ...)
- Retrieve a collection - How to get a collection or resources
- Asynchronicity - How to handle long operations
- Dereference Relationships - How to load a resource and its linked resources in one call
- Translator - Tools for translating between various API definitions, allowing the transformation from RAML to Swagger, and between each API definition format.
- Command Line - Command line tooling for use as part of the API design process, allowing developers to use single commands at the prompt.
- Github Sync - The ability to store and sync API definitions with Github, providing a central public or private repository for the definition of an API resource.
- Validator - Tools for validating API calls, enabling developers to determine which types of calls will be valid, using central API definition and schema.
- API counts - How many endpoints/resources in an API?
- Parser - An API definition parser, available in multiple languages and open up the programmatic generation of API definitions as localized object.