Contribute

Help create a microservices ecosystem that enables Banner teams to leverage enterprise data quickly and easily to drive digital transformation.

Key to the success of the platform is the ability for developers to easily understand, quickly consume and easily develop against these data services.

To provide the best possible experience for developers and fuel enterprise-wide adoption, it's important to have APIs that follow consistent design guidelines. APIs must be easy and intuitive. APIs must be thought of as 'products', not projects.

The Basics

Before you and your team can begin officially contributing to the API platform, it is important to understand the pitfalls and the prescribed best practices.

API Guidelines

To ensure APIs follow consistent design patterns and best practices, these guidelines should be followed by teams looking to include their APIs on this portal. These guidelines aim to:

  • Define consistent practices and design patterns for all API endpoints.

  • Adhere closely to accepted REST/HTTP industry best practices.*

  • Make accessing APIs easy for all application developers.

  • Allow developers to efficiently leverage the prior work of others.

  • Allow partners to design APIs to established standards for inclusion in the portal.

*The Microsoft REST API Guidelines document provides a solid framework for industry standards.

Documentation

All APIs must be fully documented to ensure developers know exactly what the API is for and how to use it. To ensure a positive experience, succinctly and accurately define each API element and write for a broad audience – readable both by experts and non-experts alike.

Include a brief paragraph of what the API is and what it provides to developers, as well as any terms and conditions of how the API can and cannot be used.

Use the latest OpenAPI standard (formerly Swagger) to document:

  • All operations, including a short description that describes its purpose

  • All response objects and their attributes

  • All parameters, including description, acceptable values, defaults, limits, example values and special instructions

  • All response codes, describing meaning in relation to the operation

  • Response body schema

Architecture

APIs included on the portal must be reliable, scalable, high performing and cost-effective. The backend service should be built with those key principles in mind. Heavy use of cloud managed services is the preferred approach. Please include an API architecture diagram when submitting your API.

Media Types

The default response media type must be JSON as outlined in RFC8259. Additional media types may be offered. The default Content-type in the response header must be application/json. Response body attribute names and URLs should follow camelCase convention.

HTTP Methods

Use standard HTTP method verbs for your API endpoint operations:

  • GET retrieve a resource or a collection of resources

  • POST create a resource

  • PUT update a resource

  • PATCH partially update a resource

  • DELETE delete a resource

Avoid mixing methods and intent within your URL, like POST /v1/getProviders

Status Codes

Responses must use standard HTTP status codes to indicate the response outcome.

Common codes:

Picture

Errors

Errors SHOULD return a message payload that provides sufficient information to understand and address the error. The RFC 7807 "Problem Details for HTTP APIs" specification provides an effective format to follow.

Example message format:

{
  "status": "400 Bad Request",
  "title": "Invalid request parameter(s)",
  "detail": "One or more request parameters did not match what is allowed and/or expected.",
  "invalidParams": [
    {
      "name": "lon",
      "value": 194.38707,
      "reason": "The value cannot be blank must be within -180.00 and 180.00 range."
    }
  ]
}

Versioning

APIs must increment the major version for any contract breaking change (per Semantic Versioning). The major version must be exposed in the URL (ex./v1,/v2).

Exposing only the major version allows non-breaking changes to be made transparently, like adding new operations and fixing bugs, without impacting existing users. Old versions must have a deprecation plan.

URL Design

The URL for a collection of resources should be formed from the resource type. For example, a collection of resources of type providers will have the URL:

/providers

Collections of resources should be treated as sets keyed by individual resource IDs. Therefore, the URL for an individual resource can be formed by appending the resource's ID to the collection URL.

For example, to perform an operation on a provider with an ID of "123456", use:

/providers/123456

Naming

Resource URIs should be based on nouns (the resource), not verbs (the methods to perform on the resource).

Avoid using verbs in the resource name like /findProvider, instead use just /providers to identify the resource and let the GET method define the intent of what to do with the resource. Correct format would be GET /providers.

Use plural nouns instead of singular when the resource represents a collection, like /providers, /facilities, /articles.

Paths

Avoid the use of confusing and inconsistent path structures for endpoints:

/v1/api/providers
/v1/facilities
/api/v1/articles

Instead, use a consistent structure like:

/v1/providers
/v1/facilities
/v1/articles

Relationships

When relationships exist between resources, use a URL structure that allows adding the related resource name to the URL.

For example, to fetch the collection of providers that practice at a particular facility, use the following:

GET /v1/facilities/9876/providers

This will present a collection of providers that practice at the facility with ID 9876.

Simplicity

In general, aim to keep your URLs simple and the URL set small. Use one base URL for your resource and utilize query strings for additional parameters.

For example, instead of having 3 separate URL endpoints like this:

GET /v1/facilities/coordinates/lat/{lat}/lon/{lon}
GET /v1/facilities/coordinates/lat/{lat}/lon/{lon}/page/{page}/size/{size}
GET /v1/facilities/coordinates/lat/{lat}/lon/{lon}/radius/{radius}

Standardize on one endpoint /v1/facilities and utilize query parameters for all the possible variations of filtering needed, like:

GET /v1/facilities?lat=32.2219895&lon=-110.8745071
GET /v1/facilities?lat=32.2219895&lon=-110.8745071&page=1&size=25
GET /v1/facilities?lat=32.2219895&lon=-110.8745071&radius=50

Dates and Times

Request input and response output should use the ISO8601 standard. Use UTC timezone (Zulu time) when possible.

Picture

Field selection

API speed and performance is critical, especially when serving mobile clients with slower transfer rates, spotty connections and data cost considerations.

In many cases, the API consumer may not need the full representation of a resource. APIs must provide developers with the ability to select returned fields. This helps optimize data payloads, minimize network traffic and speed up transfer rates.

For example, use a fields query parameter with comma separate values to allow developers to choose exactly what data is needed for the resource:

GET /v1/providers?fields=id,firstName,lastName

Inversely, provide a way to exclude a field or set of fields from the returned default data set. For example, use a - sign before the value(s) to exclude:

GET /v1/providers/?fields=-carePhilosopy,-locations

Sorting

For returned collections, provide a parameter to sort the results when appropriate. Allow the sort parameter to accept a list of comma separated fields, with the ability to indicate ascending or descending, with defaults.

GET /v1/providers?sort=lastName,firstName sort in ascending order by lastName, then firstName

GET /v1/providers?sort=-yearsOfService use a - minus sign to sort in descending order by yearsOfService value

Be sure to specify in your documentation which fields can be used for sorting.

Pagination

When requesting a resource collection, you must limit the amount of data returned by any single request to help control payload size and harden your API to DDOS attacks.

Utilize pagination parameters (with defaults) to specify starting points and the maximum number of items to fetch from the collection. Example:

GET /v1/providers?page=1&size=25

Linking

Linking should follow the RFC 8288 "Web Linking" specification (i.e. links in the Link header).

Health Checks

To help monitor uptime and troubleshoot issues, each API should include two healthcheck endpoints:

  • Simple - returns an HTTP 200 from the code running the API endpoint (not an HTML page).

  • Comprehensive - returns detailed error messages and information to help quickly troubleshoot any issues.