How to get your web API noticed

Web API discovery is a somewhat sprawling and amorphous topic. There is no one right way to achieve it, and no simple silver bullet.

This post offers a number of strategies, both aimed at your human-readable documentation and your machine-readable API definitions, to make them stand out and attract potential users.

Document your API

If nothing else, provide reference documentation and examples so people know how your API works. Aim for a low "time-to-first-200-OK"; can users access the root node of your hypermedia API, or a status page, with a simple curl request?

Slate provides a quick and easy static site generator from simple markdown to a classic three-panel documentation display.

Provide an API Portal

The next stage of API publicity is the API or developer portal. This is a home base or one-stop-shop for your API users. Some of this may only be necessary if your API is a commercial offering. It should include onboarding documentation, key / authentication management, API reference, terms of service, SLAs, pricing, support / helpdesk information, a downloadable API definition, sunset / deprecation information and anything else required during the lifecycle of using your APIs. Making everything available in one place keeps your API consumers happy and keeps them coming back for updated information.

Redoc.ly has a developer portal in-a-box offering in beta which is well worth a look.

Follow industry standards

Use of industry standards and norms will speed the onboarding process for experienced API consumers. From simply using JSON requests and responses, to following IETF RFCs for problem reporting and healthcheck status, standards for the HTTP PATCH method and sunset / deprecation information, standing on the shoulders of giants saves you API design time and potential rework in the future.

standards.rest is a great starting point to ensure that you're not reinventing the wheel.

Publish an OpenAPI document

The OpenAPI Specification [OAS] is the industry-leading API description standard. By making your API documentation machine-readable, you enable a complete eco-system of tooling which supports your API through interactive documentation and testing / mocking to client and server code generation and more.

OAS version 3.0 recommends your API definition be called openapi.yaml or openapi.json though currently makes no further suggestions on discovery.

Your API definition should be prominently linked to from your API portal, and included in your repository if your project is Open-Sourced. Don't forget to validate your API definition to make sure it is OAS compliant and lint it to make sure it is complete and consistent.

Submit to APIs.guru OpenAPI Directory

If your API meets the inclusion criteria:

• Public - anyone can access it as long as they follow some clearly defined steps (subscribe, pay fees, etc.).
• Persistent - API is made with long-lived goal, and not for a particular event (conference, hackathon, etc.).
• Useful - API should provide useful functionality not only for its owner.

then the APIs.guru OpenAPI-Directory is an excellent showcase for your API definition. It is the largest independent directory of machine-readable API definitions. Submit your API here.

The directory currently includes over 3,100 API definitions ranging from world-leading cloud vendors to self-hosted informational APIs. Inclusion in the directory automatically makes your API available to several integrated platforms and products.

Other directories / marketplaces you might consider submitting your API to include RapidAPI, the Postman Collection network and ProgrammableWeb.

service-desc Link relation type

One way to point to your OAS document is to use an HTTP Link header with a relation-type (rel value) of service-desc. More information can be found in RFC-8631

Schema.org WebAPI type

Another way to make your API and its definition discoverable is to use the Schema.org WebAPI type.

Using a format such as JSON Linked-Data (JSON-LD) you can embed machine-readable metadata in your web pages describing your API and linking to your documentation.

    <script type="application/ld+json">
    {
      "@context": "http://schema.org/",
      "@type": "WebAPI",
      "name": "Google Knowledge Graph Search API",
      "description": "The Knowledge Graph Search API lets you find entities in the Google Knowledge Graph. The API uses standard schema.org types and is compliant with the JSON-LD specification.",
      "documentation": "https://developers.google.com/knowledge-graph/",
      "termsOfService": "https://developers.google.com/knowledge-graph/terms",
      "provider": {
        "@type": "Organization",
        "name": "Google Inc."
      }
    }
    </script>

APIs.json

A little obscure and pending some work to update it, apis.json is "a machine readable approach that API providers can use to describe their API operations, similar to how web sites are described using sitemap.xml".

This format can come into its own when you have a number of APIs to describe, and need to link to various documentation and support pages for each.

Others?

Please let me know if you think I've missed anything important in this round-up, and I'll be sure to update and credit you.

Thanks

To Aijaz Ansari for inspiring this post with a question on Twitter.