How to Get Started with APIs

Mar 12, 2013

Audit

  1. Research existing APIs
    Children's building blocks letters spelling A P I.

Regardless of your agency’s level of progress in API production, your first step is to create a developer hub that links to any of your agency’s existing APIs. This can help identify current efforts and connect you with others in your agency already working on APIs.

Follow up with a deeper scan for APIs that your agency may already be publishing:

Target site-specific search queries using advanced search operators within commercial search engines. You may be able to find APIs from your agency by searching queries such as:

These queries can help you find loose APIs already generated by other teams at your agency. A quick review of 10+ pages of results are recommended because results from one API may take up the first few pages before returning results from a different API. The same queries should be performed for each of your domains. This can help jumpstart an agency’s developer hub with minimum effort.

Review repositories including Programmable Web, USgovXML, and Data.gov. Each of these indexes includes other material, requiring you to search for your agency name or abbreviation, then filter the results in different ways.

  1. Audit existing content and services

Review current Web services, for example, a system for checking the status of a request online. You can find some great potential candidates to take an existing Web service and make it available via API.

  1. Weigh early candidates for API production

Of candidate items you’ve assembled in the previous step, ask the following questions:

  • Which receive the most site traffic?
  • Which does the agency see as the most important to its mission?
  • Which would particularly lend itself to integration in a mobile app, embedding on third-party sites, or combining with another data set in a mashup?
  • Which are particularly easy to make available as APIs? (note step 6)

Each agency has different priorities and needs that will impact these questions, but combine the answers to those questions to decide on top candidates for making available via API.

If your agency is just getting started with API generation, it may be worth beginning with low-hanging fruit—services that would be easy to produce. Alternatively, there are also successful examples of agencies starting with their largest and most popular datasets for greatest impact.

Assemble Components

  1. Coordinate with relevant stakeholders

As with any addition to an agency’s Web presence, it is important to work with your agency’s network operations team, IT security team, and general counsel per your normal workflows. For some, this may be the first time that they have been involved in an API rollout, and they may rely on you to familiarize them with some of the underlying philosophy and methods of APIs in government.

  1. Prepare documentation and other components

Just turning on an API isn’t enough. It’s necessary to create a landing page for the documentation and related resources and to ensure that prospective users can find this material. Consult the API release kit for a comprehensive review of these components and open-source options for maintaining them.

  1. Activate the API

There are several ways to create an API. Your team may have the expertise, but if not, you should be able to collaborate with your IT department and any system owner on high-level requirements and leave the API creation to your agency’s developers. If these opportunities do not exist, some methods of API creation entail useful tools that can be operated without deep technical skills.

  1. Test

Once the API has been readied for launch, test the functionality that is documented for the API. Many agencies prefer to factor in an extra period of time for private beta testing, giving access to a select number of trusted associates to test the functionality. If not done as a formal process, it is still highly advisable to have developers review the product and thoroughly test it from outside of your network’s firewall before launch.

Your network operations staff should be able to provide automated tools for load-testing as well, a process which can identify and fix potential problems that would not otherwise become visible before launch.

Implement

  1. Create /developer hub

Each API should have a landing page. The landing pages should be linked to a main developer hub. Even if your agency is generating its first API, it is not too early to release it as part of a developer hub. If your agency already has launched several APIs but doesn’t yet have a consolidated hub, it’s definitely worth assembling one at this stage and growing it from this point on. Consult the /Developer kit for a comprehensive review of the developer hub components and open-source options for maintaining them.

  1. Plan the launch and follow-up

In the lead-up to the public launch of the API, plan for any communications push that your agency may want to do to bring attention to the API release (and/or the launching of a developer’s hub). Developers need to be aware of your API to use it. Some agencies issue a press release if the API that is produced is a substantial contribution. Use social media, publish blog posts, employ listservs or mailing lists, and promote within government communities to get the word out.

It’s important to ensure that the agency has some commitment for this API. The post-launch planning should factor in any needs for continued API maintenance and developer support. Just like any other digital project, APIs needs continued investment to be successful.

  1. Release API

When launching the API publicly, consider a soft launch. Soft launching lets you gather data on a product’s usage and acceptance before making it generally available. If there are concerns about any of the technical or practical issues involved, the agency can slowly introduce it to prospective users and monitor usage.

Then, when any resulting concerns are worked out, even weeks or months later, the agency can provide a formal announcement to ensure that the wider community eventually learns of it. Register the API at www.programmableweb.com. __

  1. Launch developer support program

​In addition to ensuring the health and uptime of the API, there should also be an associated developer support program that is now activated. Two important ingredients for any healthy API are: a feedback mechanism that allows developers to communicate with the API producer; and a means of broadcasting news and updates to developers who may be consuming the API. This role will require an owner lest it fall by the wayside.

Track progress

  1. Track Progress
_​_Monitor the API analytics as well as reviewing how developers are using the API to [track the progress of the API](http://blog.programmableweb.com/2010/09/15/metrics-for-content-apis-an-npr-case-study/). Since the goal is to support developer efforts to further spread your agency’s information and services, quickly address concerns and problems. Developers are your customers. Don’t let them give up in frustration.

Repeat

APIs are under continual development. Launch is the beginning of building this important content tool. The more that an agency grows its API catalog, the more that new developers will visit the agency’s hub and consume the agency’s content. Then, more citizens are served better and the agency’s impact grows.

Your APIs need to have staff assigned to monitor and improve them as well as helping to grow your API catalog.

Moving forward:

  • Include APIs when reviewing upcoming development projects, either of new systems or overhauls of old systems. By making a point to include API access as one of the project requirements, the production can take place far more easily and less expensively.
  • Look for opportunities to use your APIs internally. By using your own APIs to maintain applications and parts of your Web presence, you become a vested stakeholder. You will benefit by using your APIs to potentially provide new services, speed product development, and demonstrate uses of your API to external developers and customers.
  • As your agency generates more APIs, work to normalize the format, structure, and documentation of the APIs. Developers will reward a more consistent and predictable API ecosystem with greater use, but this practice also makes agency maintenance and developer support easier, too.
Originally posted by Gray Brooks on Mar 12, 2013

GSA | Washington, D.C.

Mar 12, 2013