Ensuring Discoverability - A Guide
Background
An API producer must begin by ensuring that an API homepage is available on their website, complete with quality documentation. From there, though, the producer has a number of opportunities to help potentially interested developers discover the resource.
Initial Advertising
- Most of all, be sure to email a brief announcement to the US Government API listserve, announcing the new API, sharing a link to it, and asking for feedback.
- Announce the API’s release via press release and on social media.
- Utilize stakeholder forums to ensure that traditional users of the system are aware of the new API.
- Share news on the Web Content Managers Listserve and Open Data Listserve (Anyone with a .gov or .mil email address can join by emailing listserv@listserv.gsa.gov, the message should have no subject and the body should say “subscribe open-data.”)
Add to the Agency’s Developer Hub
- If the agency or program has a developer hub (often at agency.gov/developer), reach out to the appropriate webmaster to add links there to the new API. All of an agency or program’s public APIs should be available from their respective developer hubs.
- If there’s not yet a developer hub, create one and start it off with your API and any others from the agency or program. You can easily clone this open sourced template for just that purpose.
- To ensure ready findability, be sure that agency.gov/developer and agency.gov/developers both redirect to the agency hub (or program.gov/developer and program.gov/developers, if appropriate).
Include in the Agency’s Public Data Listing
Located at www.agency.gov/data.json, the public data listing enables third parties to more easily discover an agency’s data offerings. This machine-readable file also populates the agency’s data listing on Data.gov, so correctly-formatted inclusion of an API in the public data listing ensures that it is discoverable through Data.gov.
More details, including schema details and complete guidance for the maintenance of the public data listing is available at Project Open Data.
Register the API with API Catalogs
There are several, well-established API catalogs that many developers use to find new APIs with which to engage. By ensuring that up-to-date records for each of an agency’s APIs is available on at least the major catalogs, the API producer can drive greater awareness of the service and attract new developers. Major API catalogs include:
- ProgrammableWeb - [Notes on adding]
- Mashape - [Will also add to PublicAPIs.com]
- APIs.io - [Based on apis.json schema]
Engage with Developer Communities
- A model
- Blog about the release, further updates, and examples of people using the API on the agency blog. Also consider cross-posting with DigitalGov.gov, programmableweb.com, and apievangelist.com.
- Tweet about the release, further updates, and examples of people using the API. @ relevant characters such as Alex Howard, Kin Lane, etc.
Ensure SEO for the Developer Hub
- Clean URLs
- Ensure pages are being crawled
- Ensure the metadata for those pages and how they look in search results
- Ensure there are no conflicts with the robots.txt file