API Naming Conventions & Change Policies

This policy applies to the VectorSurv API that provides agencies & 3rd-party developers access to create, read, update, and delete operations to records stored in the Gateway database.

Naming Conventions

REST

We use a representational state transfer (REST) architecture for simplicity and predictability. This is a commonly-used pattern that many developers have prior experience with. Here’s how Google summarizes REST in its API design guidelines:

Its core principle is to define named resources that can be manipulated using a small number of methods. The resources and methods are known as nouns and verbs of APIs. With the HTTP protocol, the resource names naturally map to URLs, and methods naturally map to HTTP methods POST, GET, PUT, PATCH, and DELETE. This results in much fewer things to learn, since developers can focus on the resources and their relationship, and assume that they have the same small number of standard methods.

HTTP Methods

We map the standard database methods Create, List, Get, Update, and Delete to the HTTP methods POST, GET, GET, PUT, and DELETE. Note that the GET http method is mapped to two database methods, list and get; the presence of a record id in the URL is what distinguishes their usage.

Standard method name	HTTP method	URL example
Create	POST	https://api.vectorsurv.org/noun
List	GET	https://api.vectorsurv.org/noun
Get	GET	https://api.vectorsurv.org/noun/id
Update	PUT	https://api.vectorsurv.org/noun
Delete	DELETE	https://api.vectorsurv.org/noun/id

In cases where we need to provide functionality that is not met by these methods, we have written custom methods. Each custom method will make use of one of the existing HTTP methods. To keep these custom methods as aligned as possible with the standard method names, this custom method name should be a verb.

https://service.name/version/some/resource/name/custom-verb

Nouns & Verbs

The resource noun should be a singular noun, e.g. “user” instead of “users”, and ideally one word.

Noun phrases for resources can usually be organized by nesting (see section below) but when they cannot be, they should be kebab-case.

Query Params

Most search functionality can be handled by the existing search and query URL params, but sometimes we need to add a custom param. In this case, the key should be lowercase and snake_case.

https://api.vectorsurv.org/v1/site?valid_date=”2001-01-10”

Nested Endpoints

In some cases a resource might be organized as a sub-resource of another resource. The URL path then can have many slashes to organize the hierarchy.

Resource	path
Site	/site
Site group	/site/group
Site group member	/site/group/member

Request body

Field names should be snake_case. The API request body need not, and in many cases should not, exactly match the database table column names. In general, this is an opportunity to make the API interface as simple and self-evident as possible for the user. The vocabulary should match the language the user sees on the VectorSurv Gateway UI.

Other rules:

The API should drop any _id suffix of column names

Avoid abbreviating nouns, e.g. “arthropod” should be used instead of “arthro”, except in cases where the abbreviation is more commonly used and/or the full noun would be too cumbersome

Change Policies

Whenever possible, changes should be additive-only and backwards-compatible.

Versioning

Our software products should follow semantic versioning so that each number is composed of a major version number, a minor version number, and a patch version number in the form MAJOR.MINOR.PATCH. Changes to a major version number indicate that some changes might not be backwards-compatible; changes to a minor or a patch version should always be backwards compatible for that major version.

Changes to resource or method names should ideally be backwards-compatible by, if possible, keeping the existing namespace and adding the new name. The old name should be marked as deprecated in the documentation, but should continue to work for users who are using the relevant major version. When changing to a new major version, the previous namespaces may be removed but the documentation should continue to describe the previous namespace as deprecated.

We will document end of life dates for each version, and will keep active at least the version immediately preceding the current default version.

API version lifecycle documentation will include the release and end of life dates (if yet applied) for each version:

Example version	Example Release date	Example End of life date
v0	01/01/2000	01/01/2005
v1	10/10/2003	-
v2 (default)	10/01/2004	-