Target audience: technical - including but not limited to developers, systems analysts, network administrators, IT project managers, IT managers, and CIOs.
Releasing data enables others to reuse it and create more value from it. A user-friendly data Application Programme Interface (API) will enable that to happen more easily and efficiently. It also helps to support a positive relationship between agencies and their data customers (users).
An API is software code that allows two software programs to communicate with each other without any user knowledge or intervention. It provides a software-to-software interface. Application or software developers use data APIs to access data or information from different sources.
To ensure your data API is user-friendly you should:
All data APIs need clear and concise documentation that doesn’t make assumptions about prior levels of knowledge.
The documentation should include:
Make common tasks easy. Make rare tasks possible but don't make them the focus. Minimise the number of endpoints you have. If developers find your API easy to memorise while completing common tasks then you might be onto a winner.
Keep your read-only data API separate from any transaction (read/write) API. The level of protection and authentication required for a transaction API is greater than for read-only so, if they’re combined, you end up requiring more robust authentication than required for open data.
Adding functionality increases complexity, so be mindful when you add new functions, as they:
Good APIs convey their purpose through descriptive, unambiguous naming and by following common URL endpoint + verb patterns.
(Although they should, some developers won’t read your documentation until something goes wrong. )
Take the time to name things properly and test the names. During API design, print out a list of endpoints and show them to junior programmers for feedback. Ask what they think each endpoint does. Listen carefully to their responses because they’re your target audience.
Check out this line from the GitHub Gists API documentation.
"You can read public gists and create them for anonymous users without a token; however, to read or write gists on a user's behalf, the gist OAuth scope is required."
https://developer.github.com/v3/gists/
In other words, if you just want to use their API to read public gists, you don't have to bother with OAuth authentication. GitHub respects your time enough to only make you login when necessary.
Note: The GitHub API is an excellent case study in providing a simple API for a highly complex domain.
https://developer.github.com/v3/
Does your organisation require authentication to access public information on your website? A read-only data API should be no different, as it's just another channel to access public information.
Note, you can gather statistics on which resources are being requested through an API without authentication. The requirement to authenticate is also a barrier to linking data.
If you want to be able to ask "what are our 4 users from org x looking at?", then that requires the provision of personal information to access public information. An alternative approach could be to invite or encourage users to tell you what they are using the data for at the point of access.
Forgive users when they make mistakes and help them to get it right next time. Provide helpful error messages about what went wrong. Warn users if there is danger ahead — both in API response messages and in documentation.
Provide safe places to play. APIs that can be explored via a browser address bar are the best option. If that's not possible:
Use consistent language across the different API calls and response formats. For example, avoid a response ‘users’ in one place and ‘customers’ in another, if referring to the same group.
Similarly, when you're deciding whether to make endpoints singular or plural, just make everything plural so developers never need to guess (eg am I calling for ‘/people’ or ‘/person’ in this case?).
Specify the version number in the URL not in the headers, and do so from day one. Also include the version number in your documentation URLs.
Design for and offer a JSON data format from the start (where appropriate). The simplicity of the JSON format makes it efficient to use - its simplicity *is* its power.
XML is amazing for its expressiveness but often doesn't translate simply to JSON. Instead you end up with a convoluted mess (like jamming a square peg into a round hole).
Rate limit the API to prevent server performance degradation if someone tries to scrape all data, or if there’s a distributed denial of service (DDoS) attack (as anything public is at risk of being will get attacked).
For example, set a limit of 1000 records to return for any query, but document a switch that can be added to retrieve all rows. This also has the benefit of not inadvertently swamping a user with the an entire dataset when they explore the API endpoint just to see the shape of the data.
Monitor the API at the host end to track and display request metrics. This is useful to users but crucial to system security and resource management.
The technical solution implemented should have low operational costs. This increases the likelihood that it will be continued into the future as the organisation changes. Longevity increases long-term adoption.
It's important that users know and understand what permissions they have to reuse the data. This information can be provided on an informative landing page or directly on the API endpoint.
Ideally you would be using Creative Commons 4.0 CC-BY and include the licence statement or URL in the endpoint metadata as well as on your landing page with other information about the API. This way, if the developer goes directly to the API they can still discover the permissions they have to reuse the data.
Your API should be comply with open standards, both in terms of how you interact with it and the data it serves up.
For further reading about API standards go to:
Application Programming Interfaces (APIs) - NZ Digital Government
Acknowledgement:
This guidance is based on the helpful advice of Chris McDowall in an Open New Zealand discussion forum at http://groups.open.org.nz/groups/ninja-talk/messages/post/1USQCu4Ab1flXdSJzQmMlA