Data libraries, design guides, templates, integration, etc.

API Design Guides

We lead workshops with your API teams and document decisions in an API Design Guide. An API Design Guide is the written collection of planning and architectural decisions you make when building an API.

This includes request authentication/authorization, case conventions, HTTP methods and responses, and product and endpoint naming. This takes the guesswork out of how an API should be designed, and allows your customers a predictable means of integration and managing automated responses.

Examples

Product names

A collection of x, which creates a single y resource on behalf of a user (singleton-resource), would have the following product name {x} + {y}.

Endpoints

x + y, a collection of x which creates a y resource on behalf of the user, would have the following endpoint /{x}/{y}/.

Shared data libraries

We create data libraries for your developer community. Shared data libraries are re-usable object libraries within your API platform.

These contain the data names, format/type, and documentation to describe an object. This takes the guesswork out of how an API should be designed from the ground-up, and provides your customers re-usable code within their application. The more data commonality across endpoints, the less they need to code.

Examples

#%RAML 1.0 Library

types:
  confirmation:
    displayName: Reservation Summary 
    type: object
    description: 'The reservation summary of a booked hotel room/rate.'
    properties:
      checkin_date:
        type: datetime-only
        required: false
        description: ‘ISO 8601 date/time of hotel check-in.'
        example: '2019-11-15T18:00:00'
      checkout_date:
        type: datetime-only
        required: false
        description: 'ISO 8601 date/time of hotel check-out.'
        example: '2019-11-17T18:00:00' 

Templates

If we know there is any possibility of re-use, we create a template. Templates are re-usable specifications within your API platform.

A Swagger, Blueprint or RAML specification with "fill-in-the-blank" {x} fields walk your API teams through the process of creating API documentation. Particularly, when there's no technical writer on your team. This provides your customers with a predictable means of interpreting the functionality of an endpoint on a developer portal, and how it could be used within their application. It also reduces the bottleneck in your content approval pipeline, since API teams are able to create higher quality documentation before it reaches content managers.

Examples

API reference docs

This endpoint can be used on a {user_page_x} to provide your users the ability to {do_x}. It supports {parameter_desc}, {parameter_desc}, or {parameter_desc} as the `{parameter_name}`. A user can then limit their results to {user_filters}. The response includes the {object1}, {object2}, {object3}, {object4}, and {object5}.

Integration

We integrate all of your API assets on your API platform. The complete integration of data libraries, documentation, and specifications within an API platform.

#%RAML 1.0 Library
uses:
  product: ../common/product.raml
  transaction: ../common/transaction.raml
  totals: ../common/rate_totals.raml
  insurance: ../common/insurance.raml
  extras: ../common/extras.raml
types:
  reservation:
  displayName: Your Object Name
  type: object
  description: 'Your object description.'
  properties:
    product: product.product
    transaction:
      type: transaction.transaction
      required: false ...

API documentation

We create API reference documentation from concept-to-production. This includes interviewing your subject matter experts, and your customers to understand their on-boarding workflow.

Examples

  • API product overviews
  • Business use cases
  • Descriptions for each property/element
  • Getting started guides
  • Request authentication/authorization guides

API specifications

We create API specifications in all shapes and sizes. Whether starting from scratch, or giving your specifications a quick makeover, we can do the heavy legwork from start-to-finish.

Examples

  • RAML 1.0
  • Blueprint
  • Swagger 2.0
  • Swagger 3.0

Workshops

We are mediators. You know that you have problems within your organization, inconsistencies, personality conflicts, developers attached to a certain design style.

We conduct on-site and remote 3-5 day workshops to help your API developer leaders come to an agreement, and we work in priority order. We document these agreements in the form of an API Design Guide.

Examples

  • Product naming conventions
  • Collection and resource naming conventions
  • Error handling