Skip to content
i4seaAPI documentation

Versioning policy

The product and its major version are in the URL

The i4sea API serves several products. Each one has its own path, with its major version right after it:

https://api.i4sea.com.br/i4cast/v1

Each product versions on its own. A change that could break an existing integration is released only as a new major version of that product, under a new path (/i4cast/v2); i4cast/v1 itself does not change in a breaking way, and the other products are not affected.

Every product and version has its own contract, and every change to a published contract is checked for breaking changes before it is released. One API key and one plan cover every product your company has contracted.

What can change inside a version

These changes are additive and can happen at any time:

  • new endpoints;
  • new optional query parameters;
  • new fields in responses;
  • new variables in the variable catalogue (GET /i4cast/v1/forecast/variables);
  • new error codes in the error catalogue.

What never changes inside a version

  • removing or renaming a field, or changing its type;
  • removing or renaming an endpoint or a query parameter;
  • making an optional parameter required;
  • renaming a public variable name such as wind_speed_10m. Public names belong to the API contract: they do not change when i4sea's internal models or names do;
  • removing or renaming an error code.

Build a tolerant client

To keep working through additive changes:

  • ignore response fields you do not know;
  • look series up by name, not by position;
  • pass variables explicitly when your code depends on an exact set of series, instead of relying on the default set;
  • handle an unknown error code by its HTTP status.

The contract

The API reference is generated from the same OpenAPI contracts the API is built against, one per product and version. You can download each one from its reference page to generate a client or validate responses.

model.name in a forecast identifies the model that produced the data. It can differ from one point to another and change as i4sea adds models, so do not hard-code model names.