Fork me on GitHub

Minimum API Portal

This is a forkable, reusable API portal that runs using Jekyll. It is meant to be a single checklist that API providers can use to setup a developer portal, and make sure they are providing the minimum amount of documentation, and other resources that developers are used to.

Authentication

This the authentication page for this template API portal. It should provide as much detail as possible about how to authenticate with an API. Try to keep things as concise as possible, and explain it like you are explaining to someone who knows nothing about your API. Make sure and try to use common approaches to API authentication.

  • Open API (Publicly Available) - We do not use authentication, with all API paths left open to the public.
  • Basic Authentication - We employ Basic Authentication for making calls to the API, requiring user and password sent as headers.
  • API Keys - We employ a public keys and secret key for making calls to the API, sent as headers.
  • OAuth - We use OAuth to secure the API, and manage access to information.
  • JSON Web Tokens - We use JSON Web Tokens to secure the API, and manage access to information.
  • Custom Authentication - We use a custom or proprietary approach to authentication for all API calls.

Consider also providing an authentication tester, and if oAuth is used, it can be helpful to allow developers to manually generate access tokens, to simply making test API calls. Remember authentication is one of the biggest areas struggle with when onboarding, so keep it as simple as possible.

Paths

Products

/products (GET)

The description of the product.

Parameters:

name in description required type format
query query The query of search. false string string
page query The page to show. false string string

Responses:

name description definition
200 An array of products Product
default Unexpected error

Services

/services (GET)

The description of the service.

Parameters:

name in description required type format
query query The query of search. false string string
page query The page to show. false string string

Responses:

name description definition
200 An array of services Service
default Unexpected error

Definitions

Product (object)

Properties:

name type description
product_id string Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles.
name string Name of product.
description string Description of product.

Service (object)

Properties:

name type description
product_id string The unique id for the service.
name string Name of service.
description string Description of product.