Common data model libraries, API design guides, documentation, and templates. 

API Design Guides

API Design Guides describe the design standards for your API development teams. Including standard case conventions, HTTP methods and responses, and product and endpoint naming. This takes the guesswork out of how an API should be designed, and allows your customers a predictable means of managing automated responses.

Examples

Collections and resources

/hotels: is used to describe the hotels collection. The collection name should be plural (ex: /hotels), and the resource singular (ex: reservation), as it is creating, updating or canceling a single resource. That is, a single hotel reservation.

Product names

A collection of x, which creates a single y resource on behalf of a single user (singleton-resource), would have the following product name {x} + {y}. 

Example: A collection of Hotels, which creates a single reservation resource on behalf of a single user (singleton-resource), would have the following product name: Hotel Reservation. 

Endpoints

x + y, a collection of x which creates a y resource on behalf of the user, would have the following endpoint /{x}/{y}/.

Example: Hotel Reservation, a collection of Hotels, which creates a reservation resource on behalf of the user, would have the following endpoint: /hotels/reservation/.

Methods

The GET method should be used to read/view a resource that is not likely to change, such as to view descriptive text of a desired hotel location.

Example: Hotel Amenities retrieves descriptive text of a hotel, including hotel property and room amenity information.

Raml 1.0

Common data libraries

Common data model libraries provide re-usable data naming standards for your API development teams. Including standard case conventions, names, and descriptions. This takes the guesswork out of how an API should be designed from the ground-up, and provides your customers re-usable code within their application. The more data commonality across endpoints, the less they need to code.

Examples

#%RAML 1.0 Library

types:
  confirmation:
    displayName: Reservation Summary 
    type: object
    description: 'The reservation summary of a booked hotel room/rate.'
    properties:
      checkin_date:
        type: datetime-only
        required: false
        description: ‘ISO 8601 date/time of hotel check-in.'
        example: '2019-11-15T18:00:00'
      checkout_date:
        type: datetime-only
        required: false
        description: 'ISO 8601 date/time of hotel check-out.'
        example: '2019-11-17T18:00:00' 

Templates

A Swagger or Raml specification with "fill-in-the-blank" {x} fields walk your API development teams through the process of creating API documentation. Particularly, when there's no technical writer on your team. This provides your customers with a predictable means of interpreting the functionality of an endpoint quickly and how it could be used within their application. It also reduces the bottleneck in your content approval pipeline, since API development teams are able to create higher quality documentation before it reaches content managers.

Examples

API description

This endpoint can be used on a {user_page_x} to provide your users the ability to {do_x}. It supports {parameter_desc}, {parameter_desc}, or {parameter_desc} as the `{parameter_name}`. A user can then limit their results to {user_filters}. The response includes the {object1}, {object2}, {object3}, {object4}, and {object5}.