API documentation

The main service in Identifiers.org is Compact Identifier resolution. Appending a Compact Identifier to the URL, as explained in the identification scheme, will redirect the requester to the relevant item in the specified resource.

The rest of the API service infrastructure is divided in two different areas: Resolution API and Registry API.

Resolution API

The Identifiers.org Resolution API is located at: https://resolver.api.identifiers.org. It provides the resolver endpoint. This is a new feature, not present in the old platform. This endpoint will return a list of the available providers for a resource, along with some information about them. Refer to the example for more details.

Resolution API services

Compact Identifier resolution
  • Endpoint: https://resolver.api.identifiers.org/{COMPACT_ID}
  • Description: Resolves a Compact Identifier and returns a list of resolved resources, sorted by its recommended usage index.
  • Example:

Registry API

The Identifiers.org registry API is located at: https://registry.api.identifiers.org. It provides a RESTful API which allows users to navigate the whole registry using the HATEOAS standard. Outside the REST API, a series of endpoints are provided for special actions, like requesting the registration of a prefix, or downloading the whole dataset. Details are provided below.

Registry API services

Data model
Mass retrieval
Prefix registration request
Usage statistics

Namespaces

Browse namespaces
  • Endpoint: https://registry.api.identifiers.org/restApi/namespaces
  • Method: GET
  • Description: Returns a portion of the namespace list in the registry.
  • Parameters:
    • page Specifies the page number requested
    • size Specifies the number of elements per page
    • sort Sorting parameter in the form field,order (eg: name,asc)
  • Example:
Find namespace by prefix
Find namespace by prefix starting with
  • Endpoint: https://registry.api.identifiers.org/restApi/namespaces/search/findByPrefixStartsWith
  • Method: GET
  • Description: Returns all namespaces in the registry which prefix start with a given string.
  • Parameters:
    • prefixStart Required Specifies the starting string.
    • page Specifies the page number requested.
    • size Specifies the number of elements per page.
    • sort Sorting parameter in the form field,order (eg: name,asc).
  • Example:
Find namespace by prefix containing
  • Endpoint: https://registry.api.identifiers.org/restApi/namespaces/search/findByPrefixContaining
  • Method: GET
  • Description: Returns all namespaces in the registry which prefix contains a given string.
  • Parameters:
    • content Required Specifies the containing string.
    • page Specifies the page number requested.
    • size Specifies the number of elements per page.
    • sort Sorting parameter in the form field,order (eg: name,asc).
  • Example:

Resources

Browse resources
  • Endpoint: https://registry.api.identifiers.org/restApi/resources
  • Method: GET
  • Description: Returns a portion of the resources list in the registry.
  • Parameters:
    • page Specifies the page number requested.
    • size Specifies the number of elements per page.
    • sort Sorting parameter in the form field,order (eg: name,asc).
  • Example:
    • https://registry.api.identifiers.org/restApi/resources?page=8&size=10
    • ↪ Gets the eighth 10-element page of the resources list.
Find resources by provider code
Find resources by namespace id
Find resources by namespace id and provider code

Institutions

Browse institutions
  • Endpoint: https://registry.api.identifiers.org/restApi/institutions
  • Method: GET
  • Description: Returns a portion of the institutions list in the registry.
  • Parameters:
    • page Specifies the page number requested.
    • size Specifies the number of elements per page.
    • sort Sorting parameter in the form field,order (eg: name,asc).
  • Example:
Find institutions by name
Find institutions by name containing
Find institutions by location country code

Locations

Browse locations
  • Endpoint: https://registry.api.identifiers.org/restApi/locations
  • Method: GET
  • Description: Returns a portion of the locations list in the registry.
  • Parameters:
    • page Specifies the page number requested.</li>
    • size Specifies the number of elements per page.</li>
    • sort Sorting parameter in the form field,order (eg: name,asc).</li>
  • Example:
Find locations by country code

Resolver dataset

Prefix request

Submit prefix registration request
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/registerPrefix
  • Method: POST
  • Description: Submits a Prefix registration request.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "name": "A new resource",
          "description": "A description with more than 50 characters for the new resource!",
          "requestedPrefix": "newres",
          "sampleId": "200",
          "idRegexPattern": "[0-9]{3}",
          "references": [
              "Reference 1",
              "Reference 2"
          ],
          "additionalInformation": ["Additional information for our new resource."],
          "institutionName": "New Resources inc.",
          "institutionHomeUrl": "https://www.example.com",
          "institutionDescription": "A description with more than 50 characters for the institution.",
          "institutionLocation": "GB",
          "providerName": "New Resources inc.",
          "providerCode": "nri",
          "providerDescription": "A description with more than 50 characters for the institution.",
          "providerHomeUrl": "https://www.example.com",
          "providerUrlPattern": "https://httpstat.us/{$id}",
          "protectedUrls": false,
          "authHelpUrl": null,
          "authHelpDescription": null,
          "providerLocation": "GB",
          "requester": {
              "name": "John Doe",
              "email": "johndoe@example.com"
          }
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": "INVALID Prefix registration request due to ''https://www.example.com'' is not a valid URL",
      "payload": {
          "comment": "No comments on your prefix registration request",
          "token": ""
      }
  }

This request will intentionally fail due to the field institutionHomeUrl: "https://www.example.com" containing a malformed URL.

Please keep in mind this is a live endpoint creating Prefix registration request entries. We would kindly request not to use it to test your application or spam it in any other way. Preferentially, use our request form.

Prefix request validation

The following endpoints provide the validation services for all the fields in a Prefix registration request.

Validate resource name
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateName
  • Method: POST
  • Description: Validates a resource name.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "name": "resource name"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate resource description
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateDescription
  • Method: POST
  • Description: Validates a resource description.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "description": "Too short"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": "Prefix request description must be longer than 50 characters",
      "payload": {
          "comment": "VALIDATION FAILED",
          "token": ""
      }
  }
Validate resource references
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateReferences
  • Method: POST
  • Description: Validates resource references.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "references": [
              "1",
              "2"
          ]
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }

References are optional, so this endpoint will always return OK.

Validate resource additional information
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateAdditionalInformation
  • Method: POST
  • Description: Validates the additional information field of a resource.
  • Body example: 
      {
          "apiVersion": "1.0",
          "payload": {
              "additionalInformation": "My grandma's name is ..."
          }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }

Additional information field is optional, so this endpoint will always return OK.

Validate resource Sample ID
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateSampleId
  • Method: POST
  • Description: Validates a Sample ID using a provider URL.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "sampleId": "200",
          "providerUrlPattern": "https://httpstat.us/{$id}"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }

To validate a Sample ID, the Provide URL pattern where that ID must be substituted must also be provided, and the final URL must point to a working document.

Validate resource Regex pattern
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateIdRegexPattern
  • Method: POST
  • Description: Validates a Regex pattern against a Sample ID.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "idRegexPattern": "[a-z]*",
          "sampleId": "testpattern"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }

To validate a Regex pattern, the Sample ID must also be provided, so the Regex can be tested against it.

Validate institution name
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateInstitutionName
  • Method: POST
  • Description: Validates a institution name.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "institutionName": "ebi"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate institution description
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateInstitutionDescription
  • Method: POST
  • Description: Validates a institution description.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "institutionDescription": "Lorem ipsum dolor sit amet."
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate institution home URL
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateInstitutionHomeUrl
  • Method: POST
  • Description: Validates an institution home URL.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "institutionHomeUrl": "https://www.example.com"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate institution location
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateInstitutionLocation
  • Method: POST
  • Description: Validates an institution location. Locations follow the ISO-3166 Country Codes Standard
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "institutionLocation": "GB"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate institution provider name
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateProviderName
  • Method: POST
  • Description: Validates a provider name.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "providerName": "EMBL-EBI"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate provider description
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateProviderDescription
  • Method: POST
  • Description: Validates a provider description.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "providerCode": "Lorem ipsum dolor sit amet."
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate provider location
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateProviderLocation
  • Method: POST
  • Description: Validates a provider location. Locations follow the ISO-3166 Country Codes Standard
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "providerLocation": "GB"
      }
  }

    Output:

      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate provider code
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateProviderCode
  • Method: POST
  • Description: Validates a provider code.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "providerCode": "ebi"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate provider home URL
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateProviderHomeUrl
  • Method: POST
  • Description: Validates a provider home URL.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "providerHomeUrl": "https://www.example.com"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate provider URL pattern
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateProviderHomeUrl
  • Method: POST
  • Description: Validates a provider home URL. A URL pattern where the LUI of the Compact Identifier will be substituted, using the tag {$id}. An example is provided below.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "providerUrlPattern": "https://www.example.com/{$id}"
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate requester
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateRequester
  • Method: POST
  • Description: Validates a Prefix registration request requester’s information.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "requester": {
              "name": "John Doe",
              "email": "johndoe@example.com"
          }
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate requester’s email
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateRequesterEmail
  • Method: POST
  • Description: Validates a Prefix registration request requester’s email.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "requester": {
              "email": "johndoe@example.com"
          }
      }
  }
  • Output: 
      {
      "apiVersion": "1.0",
      "errorMessage": null,
      "payload": {
          "comment": "VALIDATION OK",
          "token": ""
      }
  }
Validate requester’s name
  • Endpoint: https://registry.api.identifiers.org/prefixRegistrationApi/validateRequesterName
  • Method: POST
  • Description: Validates a Prefix registration request requester’s name.
  • Body example: 
      {
      "apiVersion": "1.0",
      "payload": {
          "requester": {
              "name": "John Doe"
          }
      }
  }
  • Output: 
    {
  "apiVersion": "1.0",
  "errorMessage": null,
  "payload": {
      "comment": "VALIDATION OK",
      "token": ""
  }
}

Usage statistics

Namespace data
  • Endpoint: https://registry.api.identifiers.org/statistics/namespace/:namespacePrefix
  • Method: GET
  • Description: Retrieves usage data for namespace by prefix
  • Parameters:
    • namespacePrefix Required PathVariable Prefix of namespace data to retrieve
  • Output 
    {
  "apiVersion": "1.0",
  "errorMessage": null,
  "payload": {
      "nb_uniq_visitors": 3,
      "nb_visits": 4
  }
}
  • Example:

This feature is still in trial and may be removed in the future.

Navigation