Skip to content

Considerations

The following are some general considerations about this API that must be taken into account before consuming the service.

Compatibility

This service exposes a RESTful API designed to be backwards-compatible (whenever possible). An API is considered backwards-compatible if a client written against a previous version of the API continues to work with newer versions.

The following changes are considered backwards compatible:

  • Adding new resources (on new URIs)
  • Adding new optional request headers, form fields, query parameters, or JSON properties
  • Adding new JSON properties to existing API responses
  • Changing the order of JSON properties or array items (unless explicitly documented as ordered)

The following are breaking changes (backwards incompatible):

  • Removing or renaming existing API resources (URIs)
  • Adding new required headers, query parameters, form fields, or JSON properties
  • Removing existing request or response fields
  • Changing the data type or format of existing fields
  • Altering the meaning of existing fields

Breaking changes will result in an incremented version in the API path. Deprecated versions will remain available for a defined sunset period to allow safe migration.

Authentication

Authentication is API key-based.

All requests must include a valid API key in the apikey header, provided by Veridas. Additionally, each request must specify the apikey header indicating the target bucket.

⚠️ Note: Credentials and keys are specific per service account. You must not use credentials from one service (e.g., Service A) to interact with another (e.g., Service B). Ensure that your request comes from a registered IP address associated with the intended cloud account.

Requests

  • All requests must include the Content-Type: application/json header when applicable.
  • The API uses HTTPS with valid TLS certificates. Connections to endpoints with invalid certificates must be avoided.
  • A health check endpoint (/v1/alive) is available to verify the service status. It returns HTTP 204 No Content when the service is operational.

All API responses are JSON-encoded and include meaningful HTTP status codes:

Successful responses:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok",
  "files": [
    {
      "name": "validation-id.zip",
      "status": "approved"
    }
  ],
  "page": 1,
  "total_files": 1,
  "total_pages": 1
}

or

HTTP/1.1 204 No Content

For endpoints like /v1/alive where no content is expected.

Error responses:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "status": "error",
  "message": "Missing required parameter: filename"
}
Field Required Description
status yes "error" on failure
message no Explanation of the error (if available)

Versioning

The API version is part of the URL path:

https://api.<region>.veri-das.com/id-data-storage/v{version}/<endpoint>

Currently, the only supported version is:

v1

Example:

GET https://api.<region>.veri-das.com/id-data-storage/v1/alive

Future breaking changes will result in a new version (v2, v3, etc.), with the previous versions remaining accessible during a defined deprecation period.