Design and Build Great Web APIs/

...

/

Describing our API with ALPS

Describing our API with ALPS

Learn how to create an ALPS description document for an API.

We'll cover the following...

Creating human-readable documentation

The work of authoring an ALPS document is the process of converting the diagram (along with the property information) into a machine-readable format. This format can then be used to generate basic human-readable documentation, as well as some starter code for our implementation.

We can use this diagram along with the data properties outlined in the table below as a guide to creating an ALPS description document for our API.

Onboarding Properties

Term

Source

Notes

Identifier

Onboarding record

identifier

http://schema.org/identifier

companyName

Company's legal name

http://schema.org/legalname

address

Company's address

http://schema.org/PostalAddress

email

Company's email address

http://schema.org/email

telephone

Company's phone number

http://schema.org/telephone

maxValue

Account spending limit

http://schema.org/maxValue

status

Account status

http://schema.org/status

discount

Account discount percentage

http://schema.org/discount

Starting from the top

The first step in the process of creating an ALPS description document is to create the initial YAML document along with a title and a simple description. For our Onboarding API example, the initial document looks like this:

Press + to interact
alps:
    version: '1.0'
    title: "Onboarding API" 
    doc:
        type: "markdown"
        value: "This is the ALPS document for BigCo's **Onboarding API**"

As you can see from the example, the first element is the alps node. This node defines the object type for this document. The second element is title, and the third element is the doc node. This last node includes a simple text description along with an indicator defining the type of content. In our case, we’re just writing a simple markdown. Other supported formats are HTML and text.

Adding data properties

Next, we need to add the list of the onboarding property values (refer to the table above) to the ALPS document. Here’s what the document looks like now:

Press + to interact
alps:
    version: '1.0'
    title: "Onboarding API" 
    doc:
        type: "markdown"
        value: "This is the ALPS document for BigCo's **Onboarding API**"
    descriptor:
        - id: "identifier"
          type: "semantic"
          text: "Unique identifier for this record" 
          ref: "http://schema.org/identifier"
        - id: "companyName"
          type: "semantic"
          text: "Company's legal name"
          ref: "http://schema.org/legalName"
        - id: "email"
          type: "semantic"
          text: "Company's primary email account" 
          ref: "http://schema.org/email"
        - id: "telephone"
          type: "semantic"
          text: "Company's phone number" 
          ref: "http://schema.org/telephone"
        - id: "status"
          type: "semantic"
          text: "Account status (active inactive suspended)" 
          ref: "http://schema.org/status"
        - id: "maxValue"
          type: "semantic"
          text: "Account's maximum spending limit" 
          ref: "http://schema.org/maxValue"
        - id: "discount"
          type: "semantic"
          text: "Account's default sales discount (as a percentage)" 
          ref: "http://schema.org/discount"
...