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

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

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: https://registry.api.identifiers.org/restApi/namespaces?sort=name,asc Gets the first 20-element page of the namespace list, sorted by name.
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: https://registry.api.identifiers.org/restApi/namespaces/search/findByPrefixStartsWith?prefixStart=tax Finds all namespaces with a prefix starting with 'tax'.
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: https://registry.api.identifiers.org/restApi/namespaces/search/findByPrefixContaining?content=onomy Finds all namespaces with a prefix containing the string 'onomy'.

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: https://registry.api.identifiers.org/restApi/institutions?size=1000 Gets at most 1000 institutions from the registry. This is a hard limit, and it is still recommended to paginate and launch multiple smaller requests.
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.
    • 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/locations?sort=countryName,asc Gets the first 20-element page of locations, sorted by ascending country name.
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": "xhttps://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": "http://httpstat.us/{$id}",
		"providerLocation": "GB",
		"requester": {
			"name": "John Doe",
			"email": "johndoe@example.com"
		}
	}
}
  • Output: 
    {
	"apiVersion": "1.0",
	"errorMessage": "INVALID Prefix registration request due to ''xhttps://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: "xhttps://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.

The following endpoints provide the validation services for all of 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: "Nope"
		}
}
  • 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: "http://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, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
	}
}
  • 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 a institution home URL.
  • Body example: 
    {
	apiVersion: "1.0",
	payload: {
		institutionHomeUrl: "http://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 a 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, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
	}
}
  • 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: "http://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: "http://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: ""
		}
}

Navigation