Skip to content

Conventions

This page lists conventions used in the Inatur API, and other things that are useful to keep in mind when developing your application.

Client Generation

The API has been developed using a "spec-first" approach, so the server is guaranteed to deliver responses that exactly match those found in the Reference.

This means that the openapi.json file can be used to generate a library / SDK, making it easier to perform requests and increasing the type-safety of your application. The openapi-typescript library is a very good option for TypeScript, but there exist similar options for most languages and frameworks.

Internationalisation

Inatur has both domestic and international users, so it's important that strings are displayed in both Norwegian and English.

To this end, the API delivers all user-facing strings in the language specified in the Accept-Language header. This must be set to either "no" for Norwegian (bokmål), or "en" for English.

If no Accept-Language header is sent, Norwegian text will be returned.

Internationalisation and the authentication server

By default, the authentication server will display in Norwegian. You should make sure to override this if your application is configured to use English. See the Authentication page for more details.

Versioning

All endpoints incorporate the version number as part of their path. For example, /v1/species/big-game. This approach was taken to simply consumption of the API from a generated client.

The version of an endpoint will only increase if a breaking change is made. Other changes may be made to an endpoint whilst retaining the same version number, but these will not be breaking changes.

This means that the following guarantees apply:

  • No fields will be removed from a versioned endpoint once added, though a field may be marked as deprecated
  • New fields may be added to response objects, but these can safely be ignored if desired
  • The data type of a field will remain stable
  • The required parameters / body of an endpoint will not change
  • Enum members will not be added or removed
  • No variants will be added to or removed from oneOf / anyOf union types
  • Data validations (e.g. a regex or a minimum value) will not change

Error handling

If an endpoint can return an error, this will be clearly marked in the specification as a possible response.

The exact shape of the error response will differ depending on the kind of error, but every error will have at least one message field providing some contextual information. Note that this error may contain technical details, so isn't necessarily suitable for displaying in your application.

Validation errors

The most common form of error response you're likely to encounter is a validation error returned when user-provided input doesn't meet certain constraints.

Every validation error will contain the following values:

  • field - the field that has failed validation, and to which the message pertains. For data sent via query parameters, x-www-form-urlencoded data or JSON encoded data, this will be the name of the field.
  • rejectedValue - the value entered by the user that failed validation

See the Reference for more information about errors.