MBARI API Guide

This document provides a guide and best practices for API development at MBARI.

API Types

This document currently covers REST APIs.

API Documentation

For REST APIs, it is best to write them to support the OpenAPI specification. The benefit of this is that you can then leverage generators to automatically build documentation and client libraries for different languages. Swagger is one example of how OpenAPI APIs can be documented, but others exists. It is helpful if the OpenAPI documentation mechanism is the same across APIs so we recommend the Swagger UI.

Guidelines

In general, we try to adhere to the Google Cloud API Design Guide for API design and implementation.

Versioning

While there are no 'standard' ways of defining versions in your API, we have seemed to gravitate towards the method spelled out in the Google Cloud Guide-1/Cloud Guide-2 where you specify the version in the URL of the service itself. For example:

https://myservice.host.org/[api-name]/vX/path/to/resource

where the 'vX' indicates the version of the API you are accessing (for example v1, v2, etc.). It should match the major version number specified in the OpenAPI spec definition. Non-breaking changes and update the second dot number in the OpenAPI spec, but the 'vX' would not need to change in the URL. Backwards breaking changes, should bump the 'vX' in the URL. Note the 'api-name' is optional but is often used if you are hosting more than one API on a server.

API Authentication and Authorization

We use Bearer JWTs for our API authentication and authorization. There is some flexibility on how the application uses JWTs, but the basic mechanism is that a JWT Bearer token is attached to the 'Authorization' header. Some examples of ways to use JWTs on APIs

Register your application with an OAuth identity provider (IDP) (MBARI's Duo, Google, Slack, etc.) and let the provider handle the authentication and your application simply gets handed a JWT from the IDP and can find the user information by decoding the token. Authorization can then be handled by the application by tracking which users have which permissions. This is pretty much the way all our applications handle authorization, it is handled by the application itself after allowing the IDP to handle the authentication part.
In general, for externally used applications, they should leverage both our Duo IDP in conjunction with other IDPs for external user access. This allows our IS department to enable/disable accounts across all applications the leverage Duo.
There can be some kind of rudimentary login process (one shared username and password) which is handled by the application itself. Once the username and password are verified, a JWT can be generated by the application and returned to the browser which will then attach the JWT to the Authorization header when making API calls. This procedure lacks the granularity of individual user permissions, but that might OK for some basic access level restrictions on simple applications.

Resource Path Structure

We would refer you to the Google Guide for structuring your resource paths and we try to adhere to the practice in general.

Output Formats

This is largely application specific, but just be sure you specify in the OpenAPI specification what return formats are supported (i.e. text/plain, application/json, application/xml, etc.)

TBD