If a tree falls in the woods and no one is around to hear it, does it make a sound? If a dataset is released to the world and no one is able to access it, does it have value? Open data is more than just releasing 1s and 0s. Building access, writing documentation, ensuring standards, and other features are required for meaningful use.

The objecive of this Playbook is to guide local developers through the process of building web services that can be seamlessly integrated by the global developer community. The Global Partnership has identified 12 key “plays” drawn from successful practices from the private sector and government that, if followed together, will help developers build better digital services in support of the Sustainable Development Goals (SDGs). Many of these plays (and even the format of this Playbook) are forked directly from our friends at the United States Digital Service Playbook.

Even if you aren’t going to build the data infrastructure yourself, this guide can be sent as part of the Request for Proposals (RFP) to contractors. The SDGs represent some of the most difficult and important problems of our time. There is no room for bad or lazy technology. This Playbook is a sniff-test to ensure good and solid tech in support of the SDGs.


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

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

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 enpoints 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

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

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

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