At a recent Hackathon at Penn State University API Harmony proved useful to some hackers. One team wanted to build a recruiting app that identified a developer in LinkedIn and cross referenced his or her skills in GitHub and StackOverflow. I guess that’s what undergrads have in mind as they get ready for the job market. The team used API Harmony as a source of inspiration and to learn more about the APIs they were interested in.One of the first apps that we used to demo API Harmony was about “going to the movies on a rainy day”. How did we go about identifying APIs that were good candidates for this application?
The first goal of the app is to let users get informed about recent movies, maybe by finding reviews, or theather locations. To find an appropriate API providing such information, one can use API Harmony to search for APIs that have the term “movies” in their name or description. Such a search yields:
Search results for “movies”
We see multiple APIs as well as an indication of the number of GitHub repositories which use these APIs. For example, the Rotten Tomatoes API has been used in 27 repositories on GitHub. Clicking on the Rotten Tomatoes API leads us to a details view:
Details view for Rotten Tomatoes API
In addition to the 27 GitHub repositories, which are presented in the right accordion or by clicking the graph, API Harmony also presents 107 StackOverflow discussions likely to be related to this API.
For every repository that uses the Rotten Tomatoes API, we can further learn about other APIs used in that repository:
APIs identified by API Harmony in the billyvg/piebot repo
If a repository is of interest to us, we can directly navigate to its source code in GitHub.
Add to your bag of APIs…
Assuming the Rotten Tomatoes API is of interest – we can click the “Select” button (in top right corner of the details page) to indicate that we want to use this API. By doing so, we add this API to our bag of APIs – the ones that we are considering for our application.
Selecting an API to indicate we want to use it
Repeat for the next API within a context…
By selecting APIs, they become the context to compare other APIs against. Remember, our app aims to be useful to users on “a rainy day”. So the app should know about the current weather. Back in the search bar, we search for APIs that contain the term “weather” in their name or description. This new search yields:
Results of a search for “weather”, with the context being the Rotten Tomatoes API
Note that the search is performed in the context of the previously selected Rotten Tomatotes API. Thus, the resulting tiles, showing all found weather APIs, are sorted by the commonalities of the found API with the Rotten Tomatoes API. For example, the Weather Channel API is shown first, because it shares a common repository where the two APIs are used together. In fact, the “billvg/piebot” repository we looked at before is the one using these two APIs together. In addition, the search reveals that the two APIs share two characteristics.
Looking at the details of the Weather Channel API, we see these relationships visualized in the graph:
Detailed view for The Weather Channel API in context with the Rotten Tomatoes API
Add it to your bag of APIs…
Pushing the “Select” button will add the Weather Channel API to your bag of APIs – your context will now have two APIs. Thus, future searches will consider relationships between found APIs and both APIs in the context. Of course, the sky is the limit, and we can add further APIs to the context as we wish.
Using the APIs…
As we select APIs we start to think how to use them. One way to learn how to use an API is by looking at repositories that already use an API. Another way is to leverage specifications of the API, if available . An example is the Alchemy Language API, for which API Harmony has an Open API Specification (f.k.a. Swagger specification). Let’s say we are interested in extracting the sentiment out of a movie review, perhaps to confirm that a good review is indeed positive. A search for “sentiment” yields the Alchemy Language API. When we look closer we see that the right accordion features a “Code Snippets” tab, where we are asked to provide a programming language.
Code Snippet language selection for Alchemy Language API
We choose “Node” and select the TextGetTextSentiment endpoint. API Harmony presents us with Node.js source code to invoke that endpoint, which can be copied to the clipboard for us to use it.
Code Snippet for TextGetTextSentiment endpoint
If you look closely, you may even see an easter egg: for this specific endpoint, we show where we want to take code snippets in the future, by performing static program analysis on source code of repositories that use an API. This way, we want to understand better how APIs are used and what to recommend as a best practice.
Note that not all APIs have code snippets – the availability of a specification files gates this feature. @erikwittern pointed out last weekin this blog that API specifications are not that easy to come by. We are trying to make that more pervasive, though. In the meantime, when a specification is available, you will find code snippets available for it in your language of choice in API Harmony.
Try it during your next concept phase or are your next Hackathon…
When constrained for time, like in a Hackathon, API Harmony can quickly get you started in finding suitable APIs, similarity between APIs, or code examples to copy and paste.
Look for us at Techcrunch 2016 Disrupt NY Hackathon
API Harmony will be at the TechCrunch NY Disrupt Hackathon in Brooklyn, NY this weekend (May 7th-8th), helping hackers search for APIs – and helping us, the API Harmony team, to build their own hack. Try API Harmony at ibm.biz/apiharmony or stop by the IBM/Bluemix sponsorship table to learn more and get a cool sticker. If you have any suggestions or feedback, plese comment here, push the Feedback button in API Harmony, tweet to us @apiHarmony, or find us at the Hackathon.
PS: and if your hack doesn’t pan out as expected or you need a break in between hacks, you can always call the The Internet Chuck Norris Database API for a good laugh! (also listed in API Harmony)