1.0 Swagger API reference

At IBM Watson, I was the first technical writer to document the Knowledge Graph API.


Because I’d educated myself in ML (for example, by studying machine learning, I was able to write the following Swagger API reference almost entirely by myself, with minimal developer input. Please note the following PDF represents only the tip of the iceberg; I also wrote extensive documentation on the json payload parameters, not shown here for the sake of brevity:

UX contributions

The API usability was pretty raw when I documented the 1.0 version. To be frank, the API really needed a good overhaul by a developer to get to a useable version. I moved on before I could contribute to such an overhaul, so instead, I prioritized providing sample use cases and example calls. I would say that the most challenging endpoint to document was GET /relationshipsByTemplate, an in-development endpoint that required me to leverage my knowledge of the semantic web and to experiment heavily with the endpoint myself in order to come up with relevant examples.

The API has since been substantially changed. For the current docs, see the Knowledge Graph endpoints in the Watson Discovery service (link changes frequently).