I’ve got an MVC5 application that we’re using an a JSON API for various clients (mobile apps, other web applications, etc.) as well as a traditional web application. Controller actions that return JSON data are the ones that are part of the API.
My question is – what’s the best way to document what functions are exposed? I’m new to this API thing, but it seems like people should be able to access and use the API without having to dig into the codebase.
Options:
- Internal Wiki – We have one. I make an article that contains all the functions that are exposed, and ideally keep it updated. This is the easiest, but least maintainable approach in my opinion. Anybody who adds or changes any of the API functions will have to go back and make sure this article is updated.
- Discovery endpoint – A well-known API path that provides a self-documenting (auto-generated?) application description that describes the paths and functions of the API.
- Some other framework I don’t know about?
1
We use RAML which is a formalized format to describe your REST services using YAML. Example:
title: World Music API
baseUri: http://example.api.com/{version}
version: v1
traits:
- paged:
queryParameters:
pages:
description: The number of pages to return
type: number
- secured: !include http://raml-example.com/secured.yml
/songs:
is: [ paged, secured ]
get:
queryParameters:
genre:
description: filter the songs by genre
post:
/{songId}:
get:
responses:
200:
body:
application/json:
schema: |
{ "$schema": "http://json-schema.org/schema",
"type": "object",
"description": "A canonical song",
"properties": {
"title": { "type": "string" },
"artist": { "type": "string" }
},
"required": [ "title", "artist" ]
}
application/xml:
delete:
description: |
This method will *delete* an **individual song**
Its formalized nature has several advantages:
- it is not ambiguous (which is often a problem with normal non-format wiki docs)
- it can be validated
- it can be used to create a skeleton of automated tests (there’s a SoapUI plugin for that)
- it can be used to generate (beautiful) documentation – see e.g. https://anypoint.mulesoft.com/apiplatform/popular/#/portals/apis/5502/versions/5487/pages/30295
- it can be used to generate clients/server code (in a similar way how this is done in SOAP) – see http://raml.org/projects.html
- you can define “trait” – e.g. pagination with defined parameters which can then be included in multiple web services. You don’t have to duplicate your documentation and you get more consistent APIs.
1