1

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:

  1. 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.
  2. 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.
  3. Some other framework I don't know about?
1
  • Related: programmers.stackexchange.com/q/191681. But if you're going to provide actual documentation (i.e. something that describes how to use the API) you'll have to update it no matter where it is located. Commented May 8, 2015 at 16:28

1 Answer 1

0

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
  • I think I might actually go this route. Might be overkill, but it sure is pretty.
    – ReimTime
    Commented Jun 10, 2015 at 17:27

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.