Posted on 08-14-2014
I got a gentle ping today, as I often do when there is a new developer hub or API launched in the federal government. This time it was located within the Department of Commerce, for the International Trade Administration, and was a new developer area, with five APIs at Developer.Trade.Gov.
I quickly went through the new developer area, which I consider passing the test for a minimum viable developer area, possessing all the essential building blocks an API developer hub needs. The only places I feel it fell short is in the feedback loop, and providing machine readable definitions for each of the five APIs.
I submitted my feedback as Github issues, on the repository for the developer hub, but when it comes to machine readable definitions for each of the five APIs, I know how easy this is, so rather than just submit issues, I figured I'd get to work generating the machine readable API definitions for Developer.Trade.Gov, and demonstrate what was possible. As I do with all of my work, I setup a subdomain, and Github repository, to store all of my work, and got to work on each of the five APIs:
- Market Research Library (Swagger)
- ITA Offices & Centers (Swagger)
- Trade Events
- Trade Leads
- Trade News & Articles
I chose to use Swagger for creating my machine readable API definitions, and while I was waiting for the Github commit to take for the Market Research Library API Swagger definition + Swagger UI, I got to work on the ITA Offices & Centers API. As I was finishing up, I reloaded the interactive docs for the Market Research Library API, and got the dreaded CORS warning:
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at http://api.trade.gov/market_research_library/search?keyword=travel. This can be fixed by moving the resource to the same domain or enabling CORS.
That is where the fun ends for me. I can keep creating Swagger specs for the other three APIs, but I won’t be able to play with them until I create a proxy to make calls through, and open up CORS on my end. I will make time to do this over the weekend, but until then the fun stops. I am hoping they will also open up CORS, but I'm sure it will take a while.
To wrap up my work, I also generated an APIs.json file for the Developer.Trade.Gov domain, listing the details for both the Market Research Library API, and the ITA Offices & Centers API--opening up the APIs to discovery by API search engines like APIs.io. When Developer.Trade.Gov publishes the APIs.json + Swagger specs under their domain, it will become more authoratative and given prominence in search engine results.
In about 2 hours, I was able to review a new developer area, and five APIs, generate two swagger specs, 1 APIs.json, publish to a Github repository where I launched interactive documentation for each of the two APIs, and wrap up with this story of my work. As with all of my work, you can find all of this work at the Github repository, and the best part is, when I pick the work back up, it is all in one location, with complete notes about what I did—helping me understand where I left off, in addition to allowing anyone else to step in and learn from the process.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- Where Do We Start With APIs At The University of Oklahoma?
- What I Would Look For When Hiring a Modern API Developer?
- The U.S. International Trade Commission Includes APIs In Latest Report
- Thank You @3Scale For Investing In The Community With @APIStrat
- Introducing API.Report, A Community API News Site
- Extract Knowledge From Audio And Video Using The Clarify API
- My API 101 Workshop At @APIStrat In Chicago Next Week
- Some Advice For The Enterprise When Beginning Your API Journey
- Machine Readable API Definition Format Swagger Matures to 2.0
- How Do We Continue Moving Green Button Data And APIs Forward?
- Beyond Public APIs In Government: Internal Access to Resources
- Can You Show Me The ROI On All Of This API Stuff Before We Commit
- In The Future APIs Will Be Default For All Cities
- No Public APIs Are Not Going Away Just Cause A Few BigCos Fumble At It
- Internal API Search Engine For Everyone At Your Company (Not Just Developers)
- If You Need Assistance With Your Healthcare API Strategy I Have The Person
- Explaining APIs To Senior Leadership: Access To Company Resources Without The IT Hassle
- A Conversation With @ijroth, @dorkitude, @antonyfalco, and @medjawii In The Next Generation API Stack Panel @APIStrat
- API Evangelist Thoughts On The Right To An API Key And Algorithmic Organizing
- Explaining APIs To Your Senior Leadership
- An API Evangelism Strategy To Map The Global Family Tree
- Thank You For Your API Evangelist Blog(s)
- Video From The Hypermedia Panel At API-Craft In Detroit Last Month
- Please Open Source Your API Before Shutting It Down
- Explaining My Work Around APIs In Higher Education To Institutions