{"API Design"}

These are the common building blocks I have pullled from my research so far.

Best Practices

  • 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.

Core Design

  • 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.

Media Types

  • 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.

Open Standards

  • 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.

Design Process

  • 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