Posted on 04-22-2014
I was introduced to the ReliefWeb API last week, which provides information including reports, jobs, training, countries, and source details on global crises and disasters going back to 1996.
The ReliefWeb API follows a trend of organizations realizing not just the potential of APIs for delivering content to mobile applications, but also the benefits of opening up publicly. As the site states:
The United Nations Office for the Coordination of Humanitarian Affairs (OCHA) originally built the ReliefWeb API to power a mobile version of the ReliefWeb website.
Since then they have normalized the interfaces for public consumption, hoping that “developers can build tools that increase exposure for valuable content and facilitate analysis for better decisions.”
The ReliefWeb API provides seven valuable API endpoints:
- Discovery - Providing discovery, navigability and insight into other APIs.
- Reports - Content API of updates, headlines and maps available on ReliefWeb.
- Jobs - Job offers available on ReliefWeb.
- Trainings - Training opportunities available via ReliefWeb.
- Countries - Countries from Reliefweb.
- Disasters - Disasters tracked on as part of ReliefWeb.
- Sources - Sources of information available on ReliefWeb.
The design of the API is pretty well thought out, providing some common, as well as some forward thinking technical elements:
- Documentation - Detailed information about all API endpoints, including content types, versions, data model, including full text and interactive version using Swagger.
- Hypermedia - Control links facilitate paging, deep cross-linking of content allows navigating between related resources, and all resources can be reached by drilling down from the top level of the API at http://api.rwlabs.org.
- Caching - Uses Cache-Control headers to point out how often ReliefWeb recommends checking for updates.
I started playing around making some calls and enjoyed the way the API flows, and excited about the potential. I do have some critique of the implementation, with the hope of influencing their roadmap.
The API initiative has a very side project feel. Its under /help/ in the address, and I'd say 90% of the projects I’ve seen deployed in this way go away—this will affect developer perspective. While I understand most API projects are often underfunded side projects, you should work to hide this. Launch at developer.reliefweb.int and give the portal its own navigation, and make a link to developers area prominent in footer or header of main ReliefWeb site—instilling confidence in API consumers.
The API documentation is complete. It has all the relevant information, it just feels fragmented, and needs some UX love. The Swagger API docs could be made to be a little more beautiful, flowing and integrated with the rest of the docs. The age of link to interactive explorer is gone, your entire doc experience should be interactive.
Key Things Up
I love that I can just start playing with API, without registration, but I’d much rather have ReliefWeb in tune with how the API is being used, and including usage patterns into its roadmap and future API design. Requiring self-service registration and API key to use isn't going to lock up the data, it will allow you to better understand how endpoints are being consumed, bottlenecks, and common usage patterns. This will all go a long way to helping evolve the API roadmap and understand ReliefWeb API consumers.
Much like I state above about it feeling like a side project, most of the essential API building blocks are there, but their are really fragmented. There are FAQs on multiple pages, docs spread across multiple pages, and support paths aren't super clear. Overall the portal and supporting building blocks just need some UX love to make sure it flows better for on boarding new developers, as well as supporting existing ones.
It is always hard to critique new APIs from governmental or non-profit organizations, because I'm just happy to see any API come out the door. This means the iteration cycles start, and things will only get better (potentially).
I could recommend other building blocks like code samples, idea and application showcase and social elements like usage of Github and Twitter, but I know they are just getting going and these things will come.
Overall I’m excited about the potential around the ReliefWeb API, that the organization has seen the benefits of APIs in their own mobile strategy, but also understands the potential of opening up these resources to the public.
Seeing deployments like the ReliefWeb API remind me that we can truly tackle many of the big problems we face in the world, rather than many of the stupid, first world problem API solutions and applications we see out of Silicon Valley.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- My Discussion Today With 6 Hypermedia Leaders At API-Craft in Detroit
- Getting To Know Jørn Wildt For The API Craft 2014 Detroit Hypermedia Panel
- Hypermedia Feels Like We Are Still Learning To Communicate With APIs
- Getting To Know Markus Lanthaler For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Kevin Swiber For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Steve Klabnik For The API Craft 2014 Detroit Hypermedia Panel
- New Indix API KickStart Program Reduces Costs For Developers
- Getting To Know Mike Kelly For The API Craft 2014 Detroit Hypermedia Panel
- A Shared, Distributed Experience(Metrics) Layer For The API Driven Application Stack
- Showcasing Your API Integrations With Other Platforms
- Increasing The Focus On APIs In Higher Education Is Important
- Getting To Know Mike Amundsen For The API Craft 2014 Detroit Hypermedia Panel
- The New StrongLoop API Server Provides A Look At Future Of API Deployment
- Models For API Driven Startups Built Around Public Data
- Will You Add Me To API Evangelist And How To Spot The Cool Kids
- When I Remix APIs Using Swagger How Do I Deal With Authentication Across Multiple APIs
- It Takes A Team Of Evangelists To Raise An API
- Support For Only Two Creative Commons Licenses In The API Commons
- Machine Readable Terms of Service Didn't Read Applied To APIs Via APIs.json
- API Deployment For Non-Developers Using Zapier, Google Docs, and APISpark
- State of Hypermedia Today @ API Craft In Detroit
- Need A Formal API Standard For Your Government Agency? Fork 18F's, And Make It Your Own!
- CORS Makes Your API Portable And Remix-able
- Chief Data Officer Needs To Make The Department Of Commerce Developer Portal The Center Of API Economy
- An API Definition As The Truth In The API Contract