Syntax and Style
- Document Status: DRAFT
Summary
This page contains information regarding the programmatic syntax specifications, coding styles, and best practices for the NCMNS API.
Request Endpoints
Structure
[base url]/api/[version number]/[path]?parameters
Example: https://data.naturalsciences.org/api/v2/data-products/checklists/mdd
Component |
Definition |
base_url |
The root domain (and subdomain) in a URL. Base URLs are shared by every request https://data.naturalsciences.org) |
version_number |
API Version. Endpoints are grouped and versioned at the resource class level. Currently, service endpoints use version 1.0. Data product and vocabulary endpoints use version 2.0. |
path |
The hierarchical scheme used to generate paths is as follows: [resource class]/[resource type]/[resource name], which includes everything between the API version number and an optional trailing question mark to distinguish URL parameters from the path. |
parameters |
Key-value pairs used to narrow the scope of an API request, parameters are separated from the path using a question mark (e.g., https://data.naturalsciences.org/api/v2/vocabularies?guid= |
Specifications and Guidelines
- The path in the request URL reflects the hierarchical relationships in the underlying structure of the API (API Version > Resource Class > Resource Type > Resource)
- Components ('subdirectories') in a path bound by two forward slashes are hyphenated, lowercase, and plural
- The final part of a path (not bounded by a trailing forward slash) can be singular or plural depending on the nature of the requested resource.
- Numeric identifiers are specified as URL parameters in the form key-value pairs for GET requests (e.g., https://data.naturalsciences.org/api/v1/users?id=23)
- Numeric identifiers for POST, PATCH, and DELETE requests are path components (exceptions do occur) (e.g., https://data.naturalsciences.org/api/v1/users/23/update)
- If two endpoints share a response body, then only one endpoint is needed. Every endpoint should return a unique response body.
- Fewer endpoints are always better than more endpoints
Responses
JSON datasets are hierarchical sets of key-value pairs: "key": "Value". Keys are commonly referenced as 'response parameters
Keys
- JSON keys are camel-cased and begin with a lowercase letter (camelCase)
- Keys should not contain any reference to units of measurement (e.g., weight_g, weight_grams)
- Keys with boolean data type are preceded with 'is' (e.g., isNullable, isEnumerated)
- JSON arrays are special types of objects used to store collections at the same hierarchical level that can be indexed numerically. In response bodies, JSON arrays should only be used when structural conditions meet the aforementioned special case, otherwise, nested information is annotated as objects
Values
- Values should be of the corresponding key. For example, values for the key "gender" should not contain ? or NA, those are not genders
- Data types should not be mixed and preserved as defined. In JSON, strings are wrapped in double quotation marks. Integers are not. Accordingly, keys that contain values that belong to the integer data type should not be wrapped in double quotation marks.
Tabulated Conventions
Resource Classes and Types
Use |
Form |
Casing |
Separation |
Example |
Formal (Preferred) Name |
Singular |
Proper |
Whitespace |
Data Dictionary |
Path Identifier |
Plural |
Lowercase (all) |
Hyphenated |
data-dictionaries |
JSON Key/Parameter |
Plural |
Camel-cased (first letter lowercase) |
Capital Letter |
dataDictionaries |
Database Table |
Plural |
Lowercase (all) |
Snake-casing |
data_dictionaries |
Database Column |
Singular |
Lowercase (all) |
Snake-casing |
last_modified |
Database Table -Column Association |
Not Applicable |
Lowercase (all) |
Dot (period) |
data_dictionaries.last_modified |
Last Updated: 2022-04-25