General principles

All Mediagenix Hive APIs work in a similar way. These pages describe the general principles that apply to all APIs.

Language

All the API endpoints use the application/json content type if a body is provided in the request or response.

Syntax

Resource identifiers

The resource endpoints are named using kebab case and in plural. For example:

• api/v1/regional-certifications

• api/v1/contents/{sigmaId}/bonus-contents

Query parameters

The query parameters use camel case.

For example: api/v1/contents?title=content&productStatus=ready&productionCompany=firmA

Tenant-specific attributes

In any place in the APIs where tenant-specific attributes are used, they can be found in a nested object in the payload or query parameters with the key tenantSpecificAttributes. This makes it very explicit to the developer and user which part of the API is related to core concepts and which part of the API handles fields that are specific to that tenant.

Query parameter example: GET api/v1/search?title=content&tenantSpecificAttributes={myTenantSpecificField=test}

API payload example:

{
  "title": "content",
  "tenantSpecificAttributes": {
    "myTenantSpecificField": "test"
  }
}

API granularity

The APIs are fine-grained, especially for modifying resources, as they are more reusable. Also, performing validation on data that is not deeply nested allows for clearer validation messages.

Having fine-grained APIs also implies that we do not expand nested relations. For example, a content item that has a contactPerson attribute referencing a instance of a PSIPerson entity will only contain its sigmaId in the reponse instead of a nest object with more details about the contactPerson.

For example:

GET api/v1/contents/97fa4cc4-600b-4935-b400-f1ea05c61700

{
  ...
  "contactPerson": "f01f5366-5556-40a6-8ee0-df6745151227"
}

Transport security

The minimum required TLS version is 1.2.