A Complete (Enough) API Definition To Move On and Profile The Next API in The Stack
06 Jul 2015
I'm working to profile as many of the top, publicly available APIs out there, as part of the API Stack. While I've come to feel that no API definition will ever actually be complete, I'm working to at least establish a healthy baseline for the APIs I am profiling, while also automating as much of the process as I possibly can.
To help focus my work, I'm targeting 30 companies that I depend on to run API Evangelist, and one of the first APIs I wanted to harden my process on was the AlchemyAPI. The API is fairly straightforward in design, and operation, so it made for an easy target--so far here is what I have:
|Alchemy Author Extraction API||(edit)|
|Alchemy Authors Extraction API||(edit)|
|Alchemy Combined Call API||(edit)|
|Alchemy Concept Tagging API||(edit)|
|Alchemy Entity Extraction API||(edit)|
|Alchemy Face Detection API||(edit)|
|Alchemy Feed Detection API||(edit)|
|Alchemy Image Link Extraction API||(edit)|
|Alchemy Keyword and Term Extraction API||(edit)|
|Alchemy Language Detection API||(edit)|
|Alchemy Microformats Parsing API||(edit)|
|Alchemy News API||(edit)|
|Alchemy Publication Date Extraction API||(edit)|
|Alchemy Relation Extraction API||(edit)|
|Alchemy Sentiment Analysis API||(edit)|
|Alchemy Taxonomy API||(edit)|
|Alchemy Text Extraction (RAW) API||(edit)|
|Alchemy Text Extraction API||(edit)|
|Alchemy Title Extraction API||(edit)|
My goal was to index the AlchemyAPI operations using an APIs.json file, while define each of the APIs using Swagger. I want each Swagger definition to be as complete as possible, so I can actually generate functional APIMATIC SDKs, and function Postman Collections--something I have achieved here.
I have everything I need from an AlchemyAPI profiling, for my needs. I have details about API operations like the pricing and terms of service, and I have each of the unique endpoints profiled at about what I'd consider to be 80% complete. All the APIs listed allow you to pass in a URL as the content source. For most of these APIs, there is also a version that allows you to pass in HTML or plain text--for now I am just profiling all of the APis which use the URL.
To help me complete this work, I am using my API questions tooling, which allow me automate what work needs to be done to each API, like ensuring there is a terms of service, parameters, data model, and security definition. Using the APIs.json file, I can ask these questions of any of the almost 1000 companies listed on the API Stack--it will help me tackle the work needed to get all the APIs in the stack profiled as complete as I possibly can.
In addition to providing a logo, description, and common URLs like website, blog, Twitter, and Github, I'm including links to APIs.json, SDKs.io profile, and Postman Collections. I haven't updated any of the SDKs.io profile, but the Postman Collection is current. I will make sure all of this is available in the Github issue I am using to coordinate work on the AlchemyAPI.
Each API could potentially be missing some parameters, and the definitions may still have some flaws (if you see any, feel free to fork and fix ;-). Shit, now I remembered I forgot to reference all the sub-models in some of the API data models. Oh well, will add to the list to be done, and get it tackled.
You will also find a link to a crude Swagger editor available for each API, and a page to ask Swagger related or APIs.json related questions. All the Swagger related ones are answered, but I'm still working the configuration of the APIs.json ones, and the Swagger editor (work in progress)--this same functionality is available for each company, and APIs I have listed on the API Stack.
Ok, well anyways..on to the next microproject (tm). I have an overhaul on my API Design white paper almost complete, and then I think I will tackle the profiling of Angelist and the Crunchbase API--two APIs I depend on to run API Evangelist.
P.S. One thing I also liked about the Alchemy API, is how easy it was to break the APIs down into the small possible units of value, and provide a single Swagger definition for each API. I think I will also provide a single Swagger specification for all of them, but for now I'll rely on the APIs.json index to link them together.