API Development Guidelines and Standards (Publishers)

This is an ever evolving set of Guidelines and Standards, but we hope that it will serve as a good reference when working through the development of APIs which will be published on the Campus API Gateway.

REST Based Endpoints

While REST is not clearly defined, we do attempt to follow some of it's general practices in using HTTP Methods to convey the action that is to be performed around a url that represents an entity or object within the system. So places to start learning about RESTful development are:

• https://swagger.io/
• Lynda.com's Designing RESTful APIs
• Safari Books Online's RESTful Web APIs
• REST API Tutorial

Url Composition

Here are few basic guidelines which will help keep in line with our naming conventions:

• All names in the url should be lowercase (query string parameters are defined in Variables below)
• Dashes (-) should not be used in urls (ie. don't have /academics/quarter-calendar)
• Service names should be plural, use /courses instead of /course.
• Separate services shouldn't be nested under each other.
  • For example, this is a recommended design for two separate services:
    • /students (contains basic student information: email, name, etc)
    • /courses
  • For example, this is not a recommended design for two separate services:
    • /students (contains basic student information: email, name, etc)
    • /students/courses

Versioning

Your APIs url should have versioning within it. The versioning should be at the level of each API, and not at a higher level for all APIs. This allows each API to grow and change individually without affecting the versioning schema for other teams APIs.

To do this set a version number in the url at the root of the APIs deployment package. This also means thinking about how your release will be run on your infrastructure, what is defined as your deployment package, and how you will limit the scope of what your application will do. This is strongly inline with microservice design patterns.

• Set the version number at the root of your deployment
  • Example: /students/v1/{endpoint}
  • Bad Example: /v1/students/{endpoint}

Within the url only the major version number should be listed. If there are no breaking changes (minor changes) to the endpoint, the major version number in the url should not change. So, what about minor version numbers?

We do not require the use of minor version numbers, but we do make it possible to use them within your API. If you would like to use minor version numbers in your API you can use the header ucsb-api-version in order pass along a major.minor version number within the request. Your web service will need to accept the header and use it for processing. Additionally, your service may also respond additional headers of api-supported-versions and api-selected-version.

• Major versions go in the url: /students/v1/students
• Minor versions may go in the request headers: ucsb-api-version: 1.1
• Allowed version information may be in the response headers: api-supported-versions: 1.0, 1.1
• Selected version information may be in the response headers: api-selected-version: 1.1

When a Major version is in the url, but no minor version is supplied in the request header (ucsb-api-version), the highest minor version of the given major version should used. If the Major version is no longer in use, an error should be returned.

Resources / Endpoints / Method Names

In REST development, endpoint names are generally nouns which line up with an entity within a domain. The endpoint name generally lines up one-to-one with the object type that will be returned. For example, the /registrations/v1/registrations/{perm} returns a Registrations object.

Example URL: https://registrar.sa.ucsb.edu/webservices/lookups/v1/{resource}

• When desired, there will be two URLs per resource
  • The first one is for a collection. Use plural names to refer to a collection (e.g. /applications, /dogs)
  • The second one is for an instance resource (eg. /applications/{id}, /dogs/{id})
• Resources should be nouns and not verbs
• Concrete names are better than abstract e.g. /dogs is better than /animals.
• Use lowercase resource names when possible
• Try to make resource names plural when possible. Use /dogs instead of /dog.
• Concatenate identifiers when needed
• When there are multiple types of resource identifiers, use a query string parameter to define the search type. Also, define a search endpoint when there is no clear unique identifier.
  • eg. /students/search?ucsbNetId=lkajs0 or /students/search?perm=1807403

Variable Names (Query String Parameters and Property Names)

Query string parameters and return object properties should be consistent in naming conventions and should be treated as standardized naming conventions for variable names.

Example URL: /students/search?ucsbNetId=lkajs0 Example Return Object:

{
    perm,
    firstName,
    lastName,
    suffix,
    email
}

• Should be camelCase.
• Should not include dashes (-).

Some known / common names are:

• perm
  • The perm number of the student
  • The perm should be treated as a string (not a number)
  • The perm number should be 7 characters in length
  • Input parameters of perm should take either 6 or 7 character values
  • No non-standard ANSI characters should comprise a perm
• quarter
  • When there is only one quarter the name should be quarter
  • When there are multiple quarter, Quarter should be used as the variable suffix
  • Quarters should be in YYYYQ format
• Id (suffix)
  • The use of the suffix Id should indicate a number
  • It should be safe to assume an Id is unique within a set
• Code (suffix)
  • The use of the suffix Code should indicate an alpha-numeric value (usually just alpha)
  • It should be safe to assume a Code is unique within a set
• Date (suffix)
  • The date value should be in the YYYYMMDD or YYYY-MM-DDT00:00:00 format.
• DateTime (suffix)
  • The date value should be in the YYYY-MM-DDT00:00:00 format.

HTTP Response Codes

Not all services will return the standardized HTTP Response, but they should try when possible. When returning an error code the body should contain a more descriptive error message.

Security

API Gateway to Backend API Service

The API Gateway will call into your backend API Service from either of these two IP addresses:

• ~54.148.126.54~ (previously)
• ~54.148.126.94~ (previously)
• ~34.220.39.178~ (previously)
• ~54.185.231.28~ (previously)
• ~52.39.40.215~ (previously)
• ~34.219.187.38~ (previously)
• ~34.220.165.137~ (previously)
• 54.203.231.224 (current)
• 54.212.104.180 (current)

We ask that all services meant to be published in the API Gateway will be protected by a firewall which has IP address restrictions in place.

Secondarily, if you choose, the API Gateway team can add a "magic string" into the headers of the requests that will go to your backend API service. This can be used a simple means of secondary authentication.

Client and End User Authentication within the Backend API Service

For any service which will expose PL2 data or above, they will be required to use authenticate and authorize client applications through Basic Authentication headers.

If the Backend API would like to make data available for clients which will be passing across the credentials of the actual user of the application, then it will need to authenticate and authorize Google OAuth JWT tokens.

Your Url vs API Gateway Url

The API Gateway's URL structure is designed to group similar functions in order to make them easy to find. Because of this the API Gateway url may be very different from the actual backend APIs url. For example, this API Gateway url:

https://api.ucsb.edu/students/lookups/v1/classlevels

is provided data from:

https://registrar.sa.ucsb.edu/webservices/public/lookups/v1/classlevels

In that example, the API Gateway is actually matching on https://api.ucsb.edu/students/lookups/v1/ to determine which API Proxy it will use for processing. The API Proxy then swaps out section of the url for https://registrar.sa.ucsb.edu/webservices/public/lookups/v1. The only part of the original url that is passed to the backend API is classlevels. This also means that every major version of the API published will have a different API Proxy associated with it. This is useful to allow the API Gateway team to deprecate older versions of APIs without causing any outages to current versions.