This is a follow up blog post of API Harmony now has an API, which showcases the advice endpoint of the API Harmony API.
As mentioned in the previous blog, the advice capacity checks your code against the known API specifications and reports potential usage issues in your code. It expects your code snippet in the POST body of the request and runs static program analysis on your code. Intuitively, it identifies the places where API requests are made, builds hybrid (concrete + symbolic) representations of the request parameters, compares against the specs of the corresponding endpoint and reports inconsistencies.
The explanations and examples of the advice endpoint could be found at API Harmony. If you would like to take a look under the hood, a previous post on Understanding Real API Practices via Big Code Analysis can walk you through the major steps after your code snippet is received by API Harmony.
At this time, we support snippets written in JavaScript using the jQuery or request libraries.
Using the Advice Endpoint
The following snippet is an example showing how to make calls to the advice endpoint, assuming you already have your service credentials. If not, please refer to the tutorial in API Harmony now has an API.
Figure 1: Code example invoking the advice endpoint
The program to be checked should be put in the post body as a string. The following figure shows an example.
Figure 2: Checking the example JavaScript snippet in the post body
Sample Responses
The API usage to Instagram in Fig. 2 passes the check against the Instagram API specs and is valid. In particular, the output suggests that API Harmony found the corresponding specs and the endpoint. Also, it observed the request used correct method (get) and all requirements on parameters were met.
Figure 3: Snippet is consistent with specs
The following two are examples suggesting issues found in the code. Figure 4 is output after we changed the https in the URL to http. API Harmony correctly identified the issue by looking at the API specs.
Figure 4: Example error message: wrong scheme
This time we changed the path .../v1/users/... to .../v1/user/... to simulate a typo scenario. API Harmony cannot find the corresponding endpoint path and thus reported it as an path error.
Figure 5: Example error message: wrong path
Potential Applications
The advice API endpoint can be used to power online API usage checking. Statically Checking Web API Requests in Atom gives a great example. Essentially, it’s a tool that can help you understand how you make API calls and check your usages in an automated way. Hence, it comes in handy in any applications that benefits from API syntax or semantic checks.
We found it’s helpful to report API usage issues before we actually run the program and debug the code based on the returned error messages, especially when the program makes multiple requests or vague error messages are returned. We are very much interested on your feedback and how you may use API Harmony API in your scenarios. Use the comments below or contact us via Twitter.