APIful Blog We're obsessed with Web APIs

Swagger Extensions to Graduate Your API

Nov 2, 2016 •

Recently @harledhes in blog post Evolutionary APIs with Microservices contrasted exposing external APIs vs internal APIs. He looked at the differences in marketing, in documentation, and in developer support. One common aspect to both APIs, is the existence of an API specification to highlight the functional aspects of the API. Many formats exist, we like the Open API Specification (better known as swagger), as it is an open format.

When an API matures, and shows potential for a new set of consumers, a provider starts to consider graduating the API. Adopting an API Management (like IBM API Connect ) service to manage the API, thinking about subscription plans, and formalizing certain attributes of the API to better market the API are the first steps.

Over the last three years we have been externalizing APIs from IBM SaaS offerings, you can see our catalog here (https://developer.ibm.com/api/list). We have enhanced the API with additional attributes that have come from internal requirements but they likely reflect some of the needs that any provider would want to capture.

First thing we have considered is to better document the provider including, name, logo, contact email, unique shortname. As well as provider preferences on how to handle their API: categories to help search engines, visibility on the different store fronts, and access roles on who can access the API. We also track the status of the API definition (draft, production) and business service status (Preview, Beta, Live) Here is an example:

  summary: My Pet APIs
  apiStatus: Draft
  serviceStatus: STAGE_LIVE
  productImage: 'https://www.cmcrossroads.com/sites/default/files/article/2015/architecture-gears-image.png'
  linktoProduct: 'https://link.to/product.html'
  uniqueShortName: PetStoreV101
  companyName: IBM
  providerEmail: y-h@us.ibm.com
    - Sales and Marketing
    - mobilefirst
    - bluemix
    - editor1@us.ibm.com
    - editor2@us.ibm.com

Next is how to document and use the API. It includes the try and buy pages on which to initiate a subscription, external links to relevant sites, and all the details on how to get started, list of programming languages to project for the code generation options, and those where the provider prefers to provide their own.

    - C + libcurl
    - Go
    - Java
    - Node
    - name: Authentication
      alternateName: ''
      content: Detail about how to Getting started for Authentication
      codeSnippets: []
    - name: Rate limiting
      alternateName: ''
      content: Detail about how the rate is control and what the rate limit is
        - languageType: Java
            - heading: Example of authentication
              snippet: auth = doing_something_do_get_authenticated; return auth.token
    trialLink: 'https://link.to/trial.html'
    buyLink: 'https://link.to/buy.html'
    - title: Download Library
      type: Download Link
      url: 'https://link.to/get/document.pdf'
    - title: Download SDK
      type: SDK
      url: 'https://link.to/get/sdk.zip'
    - endpointName: /pet/findByStatus
      endpointMethod: GET
      languageType: Java
      codeSnippet: '{ special = special_example_get_pet_status; return special}'
    - C + libcurl
    - Go
    - Java
    - Node

As you may have noticed, we took advantage of the so called “vendor extensions” capability in swagger (prefixed with x-) which lets the API provider document their own attributes in the swagger document while maintaining as much information in one document and simplifying data manipulation. Using the IBM API Connect editor we can define these extensions and let the editor validate the user input when editing the swagger. IBM API connect also uses extensions to specify the strategy and policies of the API traffic.

API Connect Editor with swagger extensions to extend API Provider definition

Have you used swagger extensions? what other extensions have you felt compelled to include in your API spec?

This post has been written in collaboration with Jim Laredo @laredoj.

Share via a Tweet or follow us for everything APIs!