API Documentation

Use the XeraFAIR REST API to programmatically assess research data FAIRness and integrate FAIR assessments into your workflows.

Base URL

https://openscience.xera.ac/fair/api/v1

Endpoints

POST/assess

Perform a FAIR assessment on a research data object.

Request Body

Parameter	Type	Description
identifier	string	Required. DOI, URL, or other persistent identifier
options.use_datacite	boolean	Use DataCite for DOI resolution (default: true)
options.use_github	boolean	Enable GitHub harvesting (default: false)
options.metric_version	string	Metric version (default: "metrics_v0.8")

Response

Returns an assessment result object with scores for each FAIR principle and detailed metric results.

GET/health

Check the health status of the API and F-UJI backend.

Response

ResponseJSON

{
  "status": "healthy",
  "service": "XeraFAIR",
  "fujiBackend": true,
  "timestamp": "2024-01-15T10:30:00Z"
}

Code Examples

cURL

Requestbash

curl -X POST https://openscience.xera.ac/fair/api/v1/assess \
  -H "Content-Type: application/json" \
  -d '{"identifier": "10.5281/zenodo.1234567"}'

JavaScript / TypeScript

Requestjavascript

const response = await fetch('https://openscience.xera.ac/fair/api/v1/assess', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    identifier: '10.5281/zenodo.1234567',
    options: {
      use_datacite: true,
      use_github: false,
    }
  }),
});

const result = await response.json();
console.log(result.summary.scorePercent); // 75.5

Python

Requestpython

import requests

response = requests.post(
    'https://openscience.xera.ac/fair/api/v1/assess',
    json={
        'identifier': '10.5281/zenodo.1234567',
        'options': {
            'use_datacite': True,
            'use_github': False,
        }
    }
)

result = response.json()
print(f"FAIR Score: {result['summary']['scorePercent']}%")

Example Response

ResponseJSON

{
  "id": "cm123abc456",
  "objectIdentifier": "10.5281/zenodo.1234567",
  "resolvedUrl": "https://zenodo.org/record/1234567",
  "metricVersion": "metrics_v0.8",
  "summary": {
    "scoreEarned": 16.5,
    "scoreTotal": 22,
    "scorePercent": 75,
    "findability": 85.7,
    "accessibility": 71.4,
    "interoperability": 66.7,
    "reusability": 71.4
  },
  "metrics": [
    {
      "id": "FsF-F1-01MD",
      "name": "Unique Identifier",
      "principle": "F",
      "status": "pass",
      "scoreEarned": 1,
      "scoreTotal": 1,
      "maturity": 3
    }
    // ... more metrics
  ]
}

Rate Limits

To ensure fair usage and service availability, the API has the following rate limits:

Tier	Limit	Window
Anonymous	10 requests	per hour
Authenticated	100 requests	per hour

Rate limit headers are included in API responses:X-RateLimit-Remaining,X-RateLimit-Reset

Error Handling

The API returns standard HTTP status codes and JSON error responses:

Status	Description
`200`	Successful assessment
`400`	Invalid request (missing identifier)
`422`	Identifier could not be resolved or assessed
`429`	Rate limit exceeded
`500`	Internal server error

Error Response ExampleJSON

{
  "error": "Assessment failed",
  "message": "Could not resolve identifier: invalid-doi",
  "code": "RESOLUTION_FAILED"
}