How to get your web API noticed
Tags: api, webapi, openapi, discovery
Published: 2020-07-06 11:19:46

---
title: How to get your web API noticed 
published: true
description: Web API promotion and discovery explained
tags: api, webapi, OpenAPI, discovery
cover_image: https://mermade.github.io/images/punch.jpg
---

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](https://github.com/slatedocs/slate) provides a quick and easy static site generator from simple markdown to a classic three-panel documentation display.

![Slatedocs](https://raw.githubusercontent.com/Mermade/shins/master/docs/screenshot.jpg)

## 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](https://redoc.ly/developer-portal) 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](https://standards.rest/) is a great starting point to ensure that you're not reinventing the wheel.

## Publish an OpenAPI document

The [OpenAPI Specification](https://github.com/OAI/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](https://apis.guru/awesome-openapi3/) 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](https://github.com/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](https://apis.guru/add-api/).

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](https://github.com/APIs-guru/openapidirectory#existing-integrations).

![APIs.guru OpenAPI-Directory](https://mermade.github.io/images/apis-guru.png)

Other directories / marketplaces you might consider submitting your API to include [RapidAPI](https://rapidapi.com/), the [Postman Collection network](https://explore.postman.com/) and [ProgrammableWeb](https://www.programmableweb.com/).

## `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](https://tools.ietf.org/html/rfc8631)

## Schema.org WebAPI type 

Another way to make your API and its definition discoverable is to use the [Schema.org](https://schema.org/) [WebAPI type](https://schema.org/WebAPI). 

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.

```html
    <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](http://apisjson.org/) 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](https://twitter.com/_aijaz_) for inspiring this post with a question on Twitter.