These are the common building blocks I have pullled from my research so far.
- Use the Web - The web brings a lot of tools to the table, make sure and learn about web technologies, and put them to use across API design.
- Simplicity - Consider simplicity at ever turn when designing APIs, providing the small possible unit of value you possibly can.
- 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.
- 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.
- SSL - Always support SSL by default when it comes to API operations.
- Host - Put sufficient thought into what the baseURL will be for making API calls.
- Resource - Consider how you craft your resources across all API operations.
- Action - Allow for standard actions to be taken across resource, but also reflect how APIs will be experienced.
- Verbs - Learn about, and put all HTTP verbs to use when designing APIs.
- 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.
- Body - Use the body of each request in a consistent way across API operations.
- Versioning - Establish, and stick to a common versioning strategy, and use throughout API evolutions.
- 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.
- 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 (https://en.wikipedia.org/wiki/HTTP_ETag), 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 - 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.
- 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 - 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 - 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 - Use ISO 8601 data elements and interchange formats for the representation dates and times.
- ISO 4217 - Use ISO 427 data elements and interchange formats for the representation currency codes.
- ISO 3166 - Use ISO 3166 data elements and interchange formats for the representation country codes.
- RDFa - Consider using RDFa for adding rich meta data to HTML representations.
- Schema.org - Consider using Schema.org representations for common data elements.
- 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.
- Parser - An API definition parser, available in multiple languages and open up the programmatic generation of API definitions as localized object.
- Interactive Documentation / Console - Generated API documentation allowing developers to make calls against APIs as they are learning about the interface, turning API education into a hands on experience.
- Validator - Tools for validating API calls, enabling developers to determine which types of calls will be valid, using central API definition and schema.
- 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.
- Command Line - Command line tooling for use as part of the API design process, allowing developers to use single commands at the prompt.
- Translator - Tools for translating between various API definitions, allowing the transformation from RAML to Swagger, and between each API definition format.
- Accept-Language - Set the language the API should be speaking using Accept-Language.d