Web service design decisions.
shay
commissioned a web service to be built to release all our data in JSON
and XML machine readable formats. I have a couple quick questions
about design decisions.
I noticed that the openstates web service require registration
and an API key to use. This process is easy, but our designer did not
require it in the web service that was created for us. Not requiring
it seems simple and easy and an article written by the sunlight
foundation "Ten Principles for Opening Up Government Information"
http://sunlightfoundation.com/policy/documents/ten-open-data-principles/
principles 6 and 8 indicate that non-registration is better. So the
question is, what are the design considerations for requring an API
key and registration vs not requiring it.
Next question. Our web service passes arguments using custom
request headers, I noticed the openstates API uses GET requests. Is
there a reason I might prefer request headers over GET requests? I
know for me GET requests are easy because I can type it into a web
browser and see the results, but I was wondering what people with more
experience than I think.
James Turk
This is great news, happy to help in any way we can.
The point about us recommending no API key and then requiring one is a
fair one, I'll do my best to address this seeming contradiction.
An API key that requires human approval, etc. leads to problems where
someone can say "I don't think they should have access" or "I don't
like what they're doing, let's revoke their key." That is clearly a
problem when it comes to opening government data.
On the other hand, an API key can be convenient, if someone is
intentionally or unintentionally disrupting the service it becomes
possible to cut them off at the source and contact them. If you need
to make a change to the API or do something that impacts availability,
you have their email addresses and can warn them, etc. We do require
keys, but they go out automatically regardless of what you put in the
request form and we only revoke them if a user is causing a service
disruption.
As for your system, either approach could work. There are other
solutions to the problems that API keys address (IP-based blocking and
asking all users to opt in to an email list for notifications of
changes, etc.) and perhaps those will work better. Also government
agencies sometimes have a problem storing any user-identifying
information and so will opt out of the API key route.
The question of headers vs. GET requests is probably one of those
never-ending ones, the truth is that there isn't a perfect answer. I
prefer GET parameters for the same reason that you mentioned, testing
in a browser is nice, and headers block that. At the same time many
people would argue that for some things headers are the "technically
correct" solution, and they may very well be correct.
I will say that for API key and for some caching-related things we do
support headers in some of our APIs, though in those cases there is
also an equivalent GET parameter.
Honestly, the mere fact that we're having this conversation encourages
me a great deal, whichever way you go, key vs. no key, headers vs.
parameters, it sounds like Alaska is going to be ahead of the curve
when it comes to open access.
-James
> --
> You received this message because you are subscribed to the Google Groups "Open State Project" group.
> To post to this group, send email to fifty-sta...@googlegroups.com.
> To unsubscribe from this group, send email to fifty-state-pro...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/fifty-state-project?hl=en.
>