1.8 Make it Easy to Access
April 15th, 2009 — Marieke GuyExternal developers are important, they can potentially add value to your service so you need to make it easy for them to do so and make sure that there is a low barrier to access. The maximum entry requirements should be a login (username and password) which then emails out a link.
If it is for a specific institution and contains what could be confidential information then it will need to contain some form of authentication that can be transmitted in the request.
If you need to use a Web API key make it straightforward to use. You should avoid the bottle neck of user authorisation, an overly complex or non-standard authentication process. One option is publish a key that anyone can use to make test API calls so that people can get started straight away. Another is to provide a copy of the service for developers to use that is separate from your production service. You could provide a developer account, developers will need to test your API so try to be amenable. If you release an open API then it needs to be open.
Make sure you support Linked Data. Also publish resources that reflect a well-conceived domain model and use URIs that reflect the domain model.
May 18th, 2009 at 11:21 am
Is this section about authentiation/suthorisation? If so, “make sure you support Linked Data” seems out of place here?
Also while, I think it is a very welcome recommendation, it carries with it a set of implications that carry across many other parts of the document, so needs to be established as a more general design principle, rather than a passing mention.
May 18th, 2009 at 11:21 am
That should say “authorisation”
July 16th, 2009 at 1:46 pm
I appreciate these recommendations in theory – makes me think of posterous.com, where registration and contribution are handled through email; by the time you get to account creation and authentication, there is already usage established and an incentive to register oneself.
However… authorisation and authentication barriers are necessary for many of us to comply with copyright and license terms on the original source data behind web services run for UK HE/FE. In GeoCrossWalk’s case this has involved:
- Authentication with UK Federation
- Agreeing to several sets of license terms for access to Digimap services
- Registering from within Digimap for more detailed access to collections on the basis of institutional subscription, agreeing to more terms of use, waiting a business day
- Finally registering for an API key and agreeing to another set of terms of use!
We’re working on an open service using publicly available data so potential web service users can at least test out the API; but the quality and quantity of results will be very different.
Agreed that the Linked Data principle could use more development and illustration, outside this section…