{your}APIs helps you create a future-proof API program.

Guides

We help teams come to a consensus on engineering, design and architectural decisions, if there is any topic of contention. We lead workshops, guide, and document decisions of your engineering teams.

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

Example

  • API Design Guide
  • API Deployment Guide
  • API Lifecycle Guide

Components

We create re-usable components within your API platform. This is usually in the form of shared data libraries for each line of business you serve.

These are generally best at the "object-level" as they contain the data name, data type, data format, and the description for each element. This takes the guesswork out of: 1) data modeling and design, 2) creating documentation, and 3) provides your application developer consumers with a re-usable code base within their application. The more design and data architecture consistency across your endpoints, the less application developers need to conversions between API requests, and the simpler it will be to integrate more endpoints, to scale.

Example

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: '2020-11-15T18:00:00'
      checkout-date:
        type: datetime-only
        required: false
        description: 'ISO 8601 date/time of hotel check-out.'
        example: '2020-11-17T18:00:00' 

Templates

We use templates to ensure your application developers get what they need out of your documentation. Templates can be in markdown or as a specification.

A "template" is a markdown, Open API, Blueprint, or RAML file with "fill-in-the-blank" {x} fields that walk your API teams through the process of creating API documentation. This is ultimately reflected on your developer portal. Templates are particularly useful when there is no technical writer on your team. These provide your API teams the ability to create high quality documentation before it reaches your developer portal, and your application developers reading it, a predictable means of interpreting the functionality of each endpoint.

Example

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

Integration

We integrate all of your components, documentation into a specification and deploy to your API platform. Or we guide your engineering teams via an API Deployment Guide.

#%RAML 1.0 Library
uses:
  component-1: ../common/component-name.raml
  component-2: ../common/component-name.raml
types:
  object-name:
  displayName: Your Object Name
  type: object
  description: 'Your object description.'
  properties:
    product: parent.child
    transaction:
      type: parent.child
      required: false ...

Documentation

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

Examples

  • API product "teasers"
  • Business use cases
  • Descriptions for each data property
  • Onboarding guides
  • Request authentication/authorization guides

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
  • Open API 2.0
  • Open API 3.0

Customer Interviews

Have you ever asked your customers what is going on "under-the-hood" of their application? What kind of complexity lies beneath? What pain points they have? How they on-board new developers to their application?

We can interview your customers and create a research findings report of their pain points. That gives you a roadmap of what to tackle first.