Why we do this. Together.

PLAY 1

Document everything

Imagine you built a web service API and then forgot about it for a year. Would your documentation be descriptive enough to immediately start using your own service? Be kind to your future self – document everything.

Checklist

1. Include an example call and response in the documentation. Something that a developer can copy and paste into the browser to validate the response.
2. Consider existing projects that automatically generate documentation sites, like Swagger, Slate, ApiDocJS, SpringRestDoc, or RAML.
3. Identify optional versus required arguments.
4. Structure the input and output response types in a table. Each row is an input argument or response field, with at least one attribute column to document the appropriate data type – e.g., string, integer, float.

Key Questions

• If a developer wants to contribute, can they find where and how within the documentation?
• Are the limitations of the returned data clear to developers to ensure proper and meaningful use?
• Are there referrals to projects that rely on the web services? If so, it may be worth including them in the documentation – at least the documentation header.
• Does your documentation or developer page require a custom solution, or can you rely on existing documentation projects?

PLAY 2

Consider the Developer Experience (DX)

The web service APIs are basic infrastructure. They are the roads that developers will drive on. Ensure that the roads are well-designed. It should be a natural joy to use the APIs. Consider the experience of the users, and the use will follow.

Checklist

1. Reference design standards for building a good API, like the White House API standards or Code Planet’s P of API design.
2. Ensure consistency across resources. For example, don’t use country codes in one query and country names in another.
3. Sit with a user and take notes on how easy it is to use the API – and then iterate.

Key Questions

• When talking to users of the API, do they think it feels well-designed? Does it have good bones? Does it inspire trust?
• Do users get stuck in the same place over and over again?
• What would Bostock do? WWBD?

PLAY 3

Be an upstanding citizen of the web

The highest form of courtesy on the web, just as in driving, is efficiency and dependability. Surprises and ambiguities lead to crashes. Natural, simple, and dependable APIs can create a vibrant ecosystem of applications that can change the world. Believe that.

Checklist

1. All URL endpoints should be durable, even when changes are made to the web service. This may require versioning your APIs.
2. Write the URL endpoints so that they are human readable.
3. Avoid using randomly generated strings or hashes in the URL, if your API is purely GET requests. These aren’t readable.
4. Use HTTP status codes. [TODO: add REFERENCE]
5. Ensure that the APIs (or at least the documentation) are discoverable on the web.
6. Employ SEO so that people can find them. [TODO: add more]

Key Questions

• What happens when you add a new resource? Will it alter existing endpoints? And will those alterations break a dependent app?
• Can you explain the structure of the URL in less than a minute? Will a user be able to adjust an example query without guidance?

PLAY 4

Be a part of the community and ask for help

There are developers eager to help. Working on the SDGs feels important, much more important than selling ads or optimizing sales. If you don’t understand something, ask the community. Even asking the question in an open, persistent forum is a contribution to the open source community. And if you are an advanced developer, contribute to the open source community!

Checklist

1. Visit the issues page of this site for this project with any questions about how to start. Example issues are available here.
2. Visit [Stack Overflow] or join a global development [Google Group] to ask for help.
3. The Global Partnership Marketplace will be a forum to raise needs for technical support or application development. You are among friends and family here.

Key Questions

• Do you know where to go to ask for help? If not, visit the issues page for this repository. Sign up for a free Github account, and pose a question to the group.
• Have you written anything for your app that might be useful to another app? If so, and when appropriate, can you contribute the code on an open source project?

PLAY 5

Build trust

You are providing a service to external users via the web – a web service. Ensuring that there are developers on the other end willing to use that service requires a reasonably high level of trust. If they build something today, can they use it tomorrow? Building and maintaining trust through openness, communication, licensing, and setting appropriate expectations is important for sustained use.

Checklist

1. Default to open licensing. Default to open everything.
2. Clarify what sort of applications the web service will support, e.g., list rate limits or constraints on origin headers.
3. Build in a monitor for API downtime. Consider, for example, something as simple as status images to display the health of the service.
4. Be very explicit about the uncertainty surrounding the data, and the implied limitations on applications.

Key Questions

• Are the limitations on both the service and supporting data immediately apparent?
• Who is the intended audience of the service? Who should be careful when relying on the service, since it’s not meant for certain applications? It cannot be everything to everyone.
• Is it easy to find where users can go to interact with a human? Is there a Google Group or a Github repository linked to the service for users to raise issues?

PLAY 6

Consider the future

The United Nations has resolved, between now and 2030, over the next 15 years, to end poverty and hunger everywhere. Does your data infrastructure have a 15 year plan? Build your infrastructure to last.

Checklist

1. Design the URL structure for extensibility. You shouldn’t have to redesign the URL entirely when a new resource is added.
2. Incorporate versioning into the URL structure, e.g., api.data.org/v1/kenya/poverty. This is a humble nod to the inevitable edits to the API.

Key Questions

PLAY 7

Plan for the long tail

Some of the most tranformational uses of your web services will be unforeseen. Plan for the edge cases. Build the API to support a broader range of applications of which you are already aware.

Checklist

Key Questions

PLAY 8

Make it easy to use

Checklist

1. Provide reference implementation. Show how to use the API.
2. Write modifiable examples. Take a look at this Mapbox example for reference.
3. Even create client-side wrappers with use, if you have the resources. This brings the service even closer to the end-use.
4. Try it out yourself!

Key Questions

• How long does it take to build a toy application on the service?
• Can the service be used in a hackathon? Even if you are not there to guide or instruct participants?
• Is there a way to easily incorporate the underlying data into a rectangular data format like CSV or an R DataFrame for statistical analysis or reporting?