18f / api-program

A complete agency API program.

18F API Program

What is it?

The 18F API Program is designed to expedite the ability for agencies to launch their own [Application Programming Interfaces] (http://www.computerworld.com/article/2593623/app-development/application-programming-interface.html), or APIs. APIs enable developers to request and exchange data with your agency. They provide an easier way for different applications and services to speak to one another through the exchange of information. A good API will enable your agency to in turn provide better data and services to the American people through a variety of uses and applications.

Unsupported, it is not uncommon for an agency to spend years launching a succesful program.

What can it do for my agency?

Participation in the program provides the following benefits:

• Jumpstarting a new agency API program;
• Provide a way for agencies to begin using their own APIs (known as 'dogfooding'); and
• Learn how to put data to work for you using API analytics.

Is this program right for me?

Small, medium, and large agencies, as well as medium and large individual teams within agencies would be fit candidates. Even among agencies with first or second generation API programs already in existence, the capacity has often not been scaled out to be a ready resource for all teams. The API Program provides such an easily launched capacity that multiple teams within one agency could legitimately want to onboard their own instance to maximize convenience and customization.

api-program's Issues

add an interagency agreement page in the sidebar

Include the Statement of Work, $$, and Period of Performance. Maybe the other caveats, too.

Think through a write api as a service

... The opposite of scraping a website. Stuffing a website?

Integrate a way for agencies to choose to use their own staff for some of the roles

https://github.com/18F/API-Program/blob/master/program_requirements.md

create page that describes the staffing, investment needed from agencies

Add section to manual on how to use the open source directly

so that they don't need to go through us

Create visuals

Steps, with high valence levels for the first time

factor in agency-x hub

https://github.com/agency-x/API

write a 'starting from scratch' how to conceive your api program

• What do people want, need.
• What might they try to do
• How could you articulate API calls that satisfies that.
• ... etc

weigh federalist for api documentation

weigh pages, federalist for hub

consider a content api variant

cc @vzvenyach

User Surveys and Feedback

weigh aws api stack

since we already have aws available, we should review the new API offerings -
http://www.techrepublic.com/article/amazon-launches-api-gateway-makes-three-aws-tools-generally-available/
http://techcrunch.com/2015/07/09/aws-announces-new-api-gateway-service/
http://aws.amazon.com/api-gateway/

integrate maturity model

Plan Agency Costs

Once the pilot stage is complete, we'll need an answer for what it cost agencies to procure this package.

Should deliverables include a simple product built w/ the API?

Since it can be hard to make the connection between API output and what you can do with it, should API Program deliverables include a simple product built on top of the API? This could be something that the agency can showcase right away and also be used by developers as reference (e.g., souped-up sample code).

This could be a viz or a website that the agency already has, just re-engineered using the API, or it could be something new.

Plot out path forward

• Carve website into new form
• Add any mvp requests to auto-api
• Memorialize schedule for an agency
• Start client discernment
• ...

gather partners

• jeff m.
• becky
• annalee
• david z.
• alan
• nick m.
• who else?

Potential FAQ

process content suggestions from leah

https://docs.google.com/document/d/1EjtmUMwlvzTcHM0e9f4s_ByG2FZx8raCORDdvrTRE4Y/edit#heading=h.ssudfyhgdlpd

Gather initial assumptions to test

Plan API Stack Requirements

• Easy to use
  • An 18F staffer should be able to train a non-technical agency staffer on how to add, edit, and remove data easily.
  • The agency staffer should be able to manage these tasks without the need for new software, since most government staff do not have admin permissions on their work computers.
• Easy for 18F to instantiate.
  • Minimal effort should be needed by 18F developers and devops to make ready new instances of it.
• Highly scalable.
  • There should be little or no limit to the number of datasets that can be added to the API. If an enthusiastic agency correctly integrates hundreds of simple data files, the API stack should not choke on the volume.
  • There should be little to no limit to the number of API hits that the API can handle. We should design the API so that it is simple yet robust. If an agency correctly published a dataset that for some reason became incredibly popular, the API should be able to scale to meet demand.
  • Cloud costs should scale linearly so that popularity and scalability are cheap.

Review the API considerations of open-data-maker

The open-data-maker project has thought through a bunch of potentially relevant issues. It's worth looking through their issues and pull requests.

https://github.com/18F/open-data-maker/issues
https://github.com/18F/open-data-maker/pulls

needed: videos/updated videos

If we want to sell this program, would be great to have a few good videos.

1. A good, govt.-specific API explainer. Like this one, updated and tweaked to be evergreen: https://www.youtube.com/watch?v=BVeiRCEwJx8. Overall, there are surprisingly few good API explainer videos in the world.
2. Overview of what this specific program offers (you know, once we figure that out). For example like these startup explainers.
   • short
   • high production

factor in interactive documentation

https://autoapi2.18f.gov/swagger-ui/

How complex should the API be?

Question: What are the advantages of this to 3rd party solutions?

possible additions - load testing, status checker

potential data discovery/selection tools

consider integrating load testing

A la https://github.com/newsapps/beeswithmachineguns or https://loadimpact.com/api-testing or the like.

weigh a 'getting started' page

https://github.com/18F/api-program/blob/gh-pages/pages/getting_started.md

Factor in 18FC/bpa as a throughput to set up sufficient labor to staff at scale

Think through url structure of an agency

Take an agency named Acme, whose URL is www.acme.gov.

How does this sound?

• The API itself should live at https://api.acme.gov.
• An endpoint would be https://api.acme.gov/name-of-file

factor in open data maker

https://github.com/18F/open-data-maker/blob/master/README.md

What should the data adding process look like?

flesh out user-stories and scenarios

https://github.com/18F/api-program/blob/gh-pages/pages/user-stories.md

integrate file-hosting-AAS

Reconsider Site Sections

Including...

• Overview
• Agency API
• Developer Hub
• Program Components
• Engagement
• Agency Manual
• 18F Manual
• Program Planning
• Get In Touch

Putting on Hold...

• User Stories
• Program Feedback
• alternate list of deliverables

What are potential limitations of the API stack?

weigh open data maker for the api stack

add a faq?

help agencies understand long term obligations for them

Plan out post-pilot staffing

https://github.com/18F/api-program/blob/gh-pages/program-planning/staffing.md

create (mobile friendly) website

Options for the API Stack

ensure website is printer friendly and includes url for those use cases

Collect examples of how other agencies add data/design their endpoints

document how to handle software updates

e.g. if python needs updating

articulate vision for long-term engagement

What does consulting with/for the agency look like after the initial engagement that delivers the complete program?

consider a FAQ page