As part of the extensive documentation written for Open Event API Server, event list endpoint with regards to event type had to be added to API Blueprint docs. The endpoint under consideration in this blogpost is:

GET https://api.eventyay.com/v1/event-types?sort=identifier&filter=[]

This endpoint returns a list of events for a specific event type. These event types are used for categorising similar types of events in the API Server. One example for an event type is : Camp, Treat & Retreat

With "slug": "camp-treat-retreat"

API Blueprint docs: 

To add the documentation in api_bluprint.apib file, we need to define the collection list and different levels using different numbers of ‘#’ . Since this endpoint is classified under the collection group Events, we first write it under # Events Collection
Now, since this is a separate and standalone endpoint, we describe the URL format for this in the following manner:

GET https://api.eventyay.com/v1/event-types?sort=identifier&filter=[]

Defining the parameters for the url includes

• Page size: 10
• Page number: 2
• Sort: ‘identifier’
• Filter_by : [none]

On the third level we define the type of request to be made along with the endpoint description, which in this case is :
### List All Events of an Event Type [GET]
Get a list of events.
This defines the GET request being made to the URL

GET https://api.eventyay.com/v1/event-types?sort=identifier&filter=[]

 The next step is adding the request headers to the docs. In the API server each request will contain the JWT Authentication token and one or more of Content-type or Accept attribute depending on the request method: GET, PATCH, DELETE or POST.
In any case the value for both of these will be:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json, (mime type for JSONAPI 0.1 specs)
Authentication token included in the following format:
Authorization: JWT <Auth Key>
 

The response obtained from making a call to this endpoint is added next.API Blueprint describes adding the Response along with the mime type.
+ Response 200 (application/vnd.api+json)

To parse this document correctly, apiary requires the response data to be added starting at column 9, which means 8 spaces have to be left before it. Indenting with TAB is currently not supported by apiary for api blueprint docs and will give rise to compilation error if tab indentation is found. If not properly indented, semantic issues will arise on compilation, but the tests proceed with a valid document. To ensure that this document is syntactically correct, we need to check once which can be done on apiary’s site. The compilation tool there raises proper issues, exceptions and errors. If the  document is valid, it is rendered side-by-side using api blueprint’s default theme. It is a helpful tool for on the fly editing for apib documentation. The tool and my copy of documentation can be found at: https://app.apiary.io/eopenevent/editor

The response data as received from making the GET request is added below. This data in this case includes

"meta": {
    "count": 1 
     },
    "data": [
         {}
     ]

Meta data contains the count of number of events for the given event-type, here : 1.
The details of each event is contained in the list defined by data. This is excluded from here as it can be simply found on  API Servers’ Documentation.

Related:
API Blueprint | Write the Docs – APIB Docs
Apiary.io
API Blueprint tutorial | Writing REST APIs – I’d rather be writing, blog