Interactive API docs for ORCID

Warning: This is a technical post aimed at developers and integrators.  That said, even if you’re non technical, you’ll be able to use the docs and explore the API to see what’s possible.  They’re really easy to work with.

At first glance, most REST APIs are a bit confusing.  REST is an architectural style, not a specification and people do things differently.  You can use things like HATEOS, but the overhead is a bit much for many.  So you head over to the documentation.  You fire up a text editor.  You code a few examples to try it out.  It takes a while, you can’t remember the content types, you have no idea of the schema, you realise you’re doing OAUTH wrong, etc etc etc.  But you get there eventually.

To reduce the pain, we’ve put a swagger interface in front of the latest ORCID public and member V2 APIs (note: not the 1.x API).  Swagger presents the user with a simple interface that lets them try out the various API endpoints by simply clicking a couple of buttons.  It has example requests, responses and error codes.  It generates curl statements you can cut and paste into bash.  Put simply, it makes it easy to try out the API before writing a single line of code.

orcid_swagger_ss

If you head over there now and put your ORCID into the box your can view your public record with a click of a button.  Try it out!

This work is part of THOR outreach activities and is one of the first things we’ve done to improve documentation and drive adoption.  We’ll be utilising the swagger based docs in our upcoming workshops and bootcamps to speed up the learning process.  If you’re interested in learning how to use the API there’s a quickstart guide.  Or find Tom on twitter @tomdemeranville.