Knowing what the noob API consumer wants to do might be tricky. As a API provider you need to guess what they are looking for and generate the documentation. The search will look for the result from the fixed set of content. API documentation is without doubt the most crucial element. Stripe and others have done a good job in pushing the API docs development forward and benchmark level up. You should not satisfy with “Swagger UI”.

I’m waiting for the next step in API documentation. We have seen PDF files, then static manually updated html pages, from API specs generated documentation and more advanced code examples generating API docs engines. What is the next step?

If you have not yet noticed, the Stripe API docs functionality has been updated lately (?). Or then I missed that earlier, but anyway. If you want to search from the docs, you get pretty nifty search and result view. For example I started to type “paymen” and result was:

Next step

This actually gave me an idea of possible idea to try. What if we could ask the documentation with natural language what we need? Just like we use search engines or Google. As a developer I want to get things done. I can type what I want to achieve. I don’t want to be pointed to spots in fixed documentation. I want just the basic information on how to do what I just typed. Give me code examples how to do that and brief desciption of the parameters for the API. If what I want to achieve requires calling multiple APIs, then give me the examples. And by the way, I want to say which framework of programming language I prefer.

Dream or possible?

What do we need to get prototype done? All needed should be there already available. One could solve the problem by using API driven services. Well, some code should be written but building a working prototype should be rather straight forward.

Researchers have tested natural language driven example generation with local APIs (refers to non-web APIs). Existing work about automatic code generation focuses on two extreme directions. One is trying to obtain the expected whole code (containing API usage patterns) from one natural language query and can be directly executed without any modification. This is much desirable but has only relatively poor prediction accuracy since it is essentially challenging. The other direction is to generate asmall part of critical code elements with a high prediction accuracy such as API sequences. Such critical code elements are truly beneficial to developers, but they miss some useful clues for further completing the source code.

Existing approaches either try to generate the whole code or only predict a small part of critical code elements such as API sequence. Meanwhile, API usage patterns, including APIs and API-related control-flow statements, have the moderate complexity, but can provide enough code framework information and are very helpful for developers to implement various functionalities.

So I’m not saying to achieve the above dream would be a walk in the park. The article “Automatically Generating API Usage Patterns from Natural Language Queries” contains some concrete examples and described how the results can be achieved with a tool. The test material for it was taken from Github, so the material is authentic and not generated/created by the researchers.

Yes, the examples are simple but you get the idea. If the above concept would be taken to API docs, it would be for example “List all products which are apps from Platform of Trust with python”. Then the response would contain the code example (in python of course because it was defined in query):

import requests

response = requests.get(
    'https://api-sandbox.oftrust.net/products/v1',
    params='type=apps'
)

print({
    'raw_body': response.json(),
    'status': response.status_code,
    'code': response.status_code
})

Next to the code example would be some additional information like the parameter options and explanations.

The process to make it work would be pretty simple thing to try as prototype:

  1. Type what you want to do (like in google search)
  2. The request is send to backend which has NLP capabilities as a service (3rd party)
  3. NLP tells what is the intent of the user
  4. Based on that code example with needed additional describing documentation is generated witth help of API specs file and then shown to me (much could be static)
  5. If the self-service tool described here can not answer, it could fallback to old-skool type API documentation. That situation would be taught to system separately and next time it could handle it.

NLP

NLP (Natural language processing) is the science of extracting the intention of text and relevant information from text. The reason why you see so many bot platforms popping up like mushrooms is the advent of many NLP as a service platforms. There’s ready-made productized solutions in the market. Some known NLP as a service platforms are

  1. LUIS.ai — By Microsoft
  2. Wit.ai — By Facebook
  3. Diagflow — By Google (Funny thing is that API docs say “Warning: V1 of Dialogflow’s API will be shut down on October 23, 2019.”)
  4. Watson — By IBM

Code example generation

Use gode generation tools available. We did one more solution at Platform of Trust for code generation for selected programming languages. It’s driving our “Stripe style” API documentation. With some modifications, that engine could be harnessed here as well. At the moment it handles cURL, python and JS, but it’s easy to expand to include any amount of languages.

A thing towards the idea

No more static API docs but google-alike “Ask Jeeves” natural languages API docs. A really limited test version of this was built 2017. I was lucky to be involved in building this prototype-ish thingy which did lack code example generation but it did contain natural language processing (with api.ai)

Furthermore I’m not alone with this idea. I friend of mine Jani Karhunen has done some work on this already

Some more to read from 100 Days DX