Creating records via the API
This page describes how to use our REST API to create records in FAIRsharing
In order to create records in FAIRsharing via the API, you'll need an account and also to have associated your user profile with an organisation.
Although our REST API does have some ability to make queries, if you are planning to create a lot of records or need to make detailed queries about information to include in your records (e.g. IDs of linked records) then we recommend that you request a key for our GraphQL API.
Generally, most users should be using our graphical editor for ease of record creation. However, the method below can be used by those who need to create multiple records in an automated way. Whether the record is created via the website or API, the record creator/maintainer will receive an email with information on whether any required fields are missing (a summary of these fields will be added here later). Records will only be approved once all required fields are present.
Important Note
The URLs used in the document below are https://api.fairsharing.org. This is our production server and any records created here will be visible to the public and issued with DOIs once they have been reviewed by our curators.
We'd appreciate it if, for testing purposes, you would use https://dev-api.fairsharing.org. This is a copy of the site which can be used to create test records, and records can be added or deleted here without any issue. If you find you can't log in to it, please contact us. To view records you've created there, please log in to https://preview.fairsharing.org.
From time to time the dev-api server may be over-written with the latest data, and so it should not be used for storing records permanently.
Authentication
You'll need to get a JWT (JSON Web Token) to use the REST API. These are valid for 24 hours and can be obtained by a POST with the following data:
POST https://api.fairsharing.org/users/sign_in
{
"user":
{
"login": "your_username",
"password": "your_password"
}
}A successful login will return your user object, including the JWT you will need for further operations:
{
"success": true,
"jwt": "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxYjhjMmMwMS05MjAsg3LTQxOGUtOTNiNS04NjNjNDE1NWZmM302LCJzdWIiOiI2NzMiLCJzY3AiOiJ1c2VyIiwiYXVkIjpudWxsLCJpYXQiOjE2MTQzMzk1MTMsImV4cCI6MTYxNDQyNTkxM30.QzTDIeDCvHc49lLbztxB5roGtIUuOTlRIOLFmiy2M6g",
"username": "joe_bloggs",
"id": 123,
"role": "user",
"profile_type": "publisher",
"watched_records": [
1
],
"is_curator": false,
"is_special_curator": false,
"expiry": 1614425000,
"message": "Authentication successful"
}You will need to add the JWT in the headers of any request you send to the API, as follows:
{
"Accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxYjhjMmMwMS05MjAsg3LTQxOGUtOTNiNS04NjNjNDE1NWZmM302LCJzdWIiOiI2NzMiLCJzY3AiOiJ1c2VyIiwiYXVkIjpudWxsLCJpYXQiOjE2MTQzMzk1MTMsImV4cCI6MTYxNDQyNTkxM30.QzTDIeDCvHc49lLbztxB5roGtIUuOTlRIOLFmiy2M6g"
}Sending Data
Here's an example of some data which could be sent to create a record. The URL to create a FAIRsharing record is:
POST https://api.fairsharing.org/fairsharing_records
{
"fairsharing_record":
{
"metadata": {
"name": "My new record",
"homepage": "http://example.com",
"abbreviation": "MNR",
"contacts": [
{
"contact_name": "John Smith",
"contact_orcid": "00000-321321321",
"contact_email": "jsmith@example.com"
}
],
"description": "This record is for my new exciting resource.",
"status": "ready"
},
"record_type_id": 1,
"object_type_ids": [1],
"subject_ids": [1, 2, 3],
"domain_ids": [1, 2, 3],
"taxonomy_ids": [1, 2, 3],
"user_defined_tag_ids": [1, 2, 3],
"country_ids": [1, 2, 3],
"publication_ids": [1, 2, 3],
"citation_ids": [1],
"organisation_link_attributes": [
{
relation: 'maintains',
is_lead: true,
organisation_attributes: {
organisation_type_ids: [1],
name: 'Example University',
homepage: 'https://example.edu',
alternative_names: ['alternate example university'],
country_ids: [1],
}
}
],
"record_associations_attributes": [
{
"linked_record_id": 1,
"record_assoc_label_id": 1
}
],
"licence_links_attributes": [
{
"licence_id": 1,
"relation": "applies_to_content"
}
]
}
}Field Descriptions
You will notice there are plenty of IDs, e.g. record_type_id, shown in this JSON example. These are the IDs of other objects within the FAIRsharing database, and are required in order to link one to the other. For example, all records require a record_type, so you would need to know the IDs of record_types in order to pick the preferred one. The recommended queries for doing this are described in the query section below, following the description of available fields. Once you have queried the database to find these IDs then they can be saved as they will not change, with the exception of certain tags where an occasional (once per year, perhaps) modification of the ontologies on which they are based may result in a renumbering. These are: subjects, domains, and user_defined_tags. Please see also the FAIRsharing schema document at Zenodo.
Metadata
This contains information about the record which isn't a link to another object in the database. For example, the record's name.
Please refer to the schema document for more information about fields that could go into metadata.
Record Type
FAIRsharing divides records into registries; Databases, Standards, Policies, Collections and "FAIRassists". Each of these can have multiple types, e.g. a policy could be a journal or a journal_publisher policy. Each type of record has its own schema fields which apply to it. A record type must be supplied.
Object Type
This is the type of object to which the FAIRsharing record refers. For example, it could be an electronic document, a questionnaire, etc. Please see object types under general information.
Tags
Subjects, domains, taxonomies and user-defined-tags can all be added to a record by supplying an array of the IDs to be added. For more information about them, see here.
Countries
A record may be linked to one or more countries by supplying an array of country ids. More information about countries is here.
Publications and Citations
Any number of publications may be linked to a record via an array of their IDs. If you also add a publication's ID to the array of citations then that publication will be shown on the record's page as a publication that can be used to cite the original resource to which the records refer. More info. on publications is here.
Organisation Links
Each organisation to which a record is linked has a relation and also notes if the organisation is the lead on that particular field. In the example shown above the organisation maintains the resource, and is_lead: true denotes that it's the main maintaining organisation. Available relations are:
maintains
funds
collaborates_on
associated_with
undefined
Each organisation_link must include an organisation, and each organisation must have a type. An optional grant can be added if the organisation's relation is 'funds'. Organisations and types can be searched for as described under the GraphQL section below. More information on organisations is here.
Record Associations
These represent other records which are related in some way to the record you're creating. Your record might, for example, be a database which implements a standard. In this case you'd supply the ID of the standard under linked_record_id and the ID of that label ('implements') under record_assoc_label_id. As before, finding the IDs of labels and other records can be done via GraphQL. Please see relations to other records for more information.
Licence Links
Any number of licences can be added to a record. Available relations are:
applies_to_content
undefinedCreating a new licence at the same time as creating a record is not currently supported, but may be in future. Please see licences and support links for more information.
Finding IDs via GraphQL
The GraphQL interface for FAIRsharing is a powerful means of querying our database in order to find available records' IDs for linking them as described above. All GraphQL queries are made as follows:
POST https://api.fairsharing.org/graphql
First, please contact us to request a key for using this endpoint. When generated it will be visible on your user profile page.
To authenticate, include the following in your request headers:
X-GraphQL-Key your_key_goes_here
Please note our licence terms when using data from this API.
Documentation
Documentation in the form of a schema showing all available queries can be found here. Click on Query to see a list of all of them.
Each definition gives the name of the query, any query parameters, and what type of data it returns. An exclamation mark shows that a field cannot be null. For example:
fairsharingRecord(id: ID!): FairsharingRecord!
...shows the query for a record, which requires an ID parameter, and returns a FairsharingRecord object. Clicking on FairsharingRecord will show the fields which can be requested. Example:
licences: [Licence!]
...shows that requesting the licences field of a FairsharingRecord object will return an array of Licence objects.
Here's how that will look when making a query to the server:
query {
fairsharingRecord(id: 1547){
name
abbreviation
type
objectTypes {
id
label
}
recordAssociations {
id
recordAssocLabel
linkedRecord {
id
name
type
}
}
}
}In addition to some basic information such as name and abbreviation, this also requests information on linked records. As each linked records is a FairsharingRecord the fields to be returned for them myst also be specified. This will produce:
{
"data": {
"fairsharingRecord": {
"name": "NCBI Genetic Sequence Database",
"abbreviation": "GenBank",
"objectTypes": [
{
"id": 5,
"label": "dataset"
}
],
"recordAssociations": [
{
"id": 2366,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1572,
"name": "DNA Data Bank of Japan",
"type": "knowledgebase"
}
},
{
"id": 2367,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1598,
"name": "Integrated Microbial Genomes And Microbiomes",
"type": "repository"
}
},
{
"id": 2368,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1620,
"name": "NONCODE",
"type": "knowledgebase"
}
},
{
"id": 2369,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1623,
"name": "GENI-ACT",
"type": "repository"
}
},
{
"id": 2370,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1661,
"name": "Joint Genome Institute, Genomes OnLine Database",
"type": "knowledgebase"
}
},
{
"id": 2371,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1726,
"name": "Influenza Research Database",
"type": "knowledgebase"
}
},
{
"id": 2372,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1850,
"name": "European Nucleotide Archive",
"type": "repository"
}
},
{
"id": 2373,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1914,
"name": "VirHostNet",
"type": "knowledgebase"
}
},
{
"id": 2374,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1938,
"name": "TIGRFAMs",
"type": "knowledgebase"
}
},
{
"id": 2375,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1969,
"name": "Expressed Sequence Tags database",
"type": "repository"
}
},
{
"id": 2376,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1982,
"name": "The Protein Database",
"type": "knowledgebase"
}
},
{
"id": 2377,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1984,
"name": "NCBI Viral Genomes Resource",
"type": "knowledgebase"
}
},
{
"id": 2378,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 1998,
"name": "Dryad Digital Repository",
"type": "repository"
}
},
{
"id": 2379,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 2211,
"name": "NCBI BioSample",
"type": "repository"
}
},
{
"id": 2380,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 2278,
"name": "Ascidian Network for In Situ Expression and Embryological Data",
"type": "knowledgebase_and_repository"
}
},
{
"id": 2381,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 2386,
"name": "Ensembl Genomes",
"type": "repository"
}
},
{
"id": 2382,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 2402,
"name": "Ensembl Bacteria",
"type": "repository"
}
},
{
"id": 2383,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 2403,
"name": "Ensembl Protists",
"type": "repository"
}
},
{
"id": 2384,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 2404,
"name": "Ensembl Plants",
"type": "repository"
}
},
{
"id": 2385,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 2405,
"name": "Ensembl Fungi",
"type": "repository"
}
},
{
"id": 2386,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 2406,
"name": "Ensembl Metazoa",
"type": "repository"
}
},
{
"id": 2387,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 2450,
"name": "Visual Database for Organelle Genome",
"type": "knowledgebase"
}
},
{
"id": 2388,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 3019,
"name": "Genomic Observatories Meta-Database",
"type": "repository"
}
},
{
"id": 2389,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 3137,
"name": "ViruSurf",
"type": "knowledgebase"
}
},
{
"id": 2390,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 3189,
"name": "MycoCosm",
"type": "knowledgebase"
}
},
{
"id": 2391,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 3200,
"name": "RNA Atlas of Structure Probing",
"type": "knowledgebase"
}
},
{
"id": 2392,
"recordAssocLabel": "related_to",
"linkedRecord": {
"id": 3306,
"name": "Paired Omics Data Platform",
"type": "repository"
}
},
{
"id": 2393,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 1280,
"name": "Short Read Archive eXtensible Markup Language",
"type": "model_and_format"
}
},
{
"id": 2394,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 1220,
"name": "NCBI Organismal Classification",
"type": "terminology_artefact"
}
},
{
"id": 2395,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 833,
"name": "GenBank Sequence Format",
"type": "model_and_format"
}
},
{
"id": 2396,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 620,
"name": "FASTA Sequence Format",
"type": "model_and_format"
}
},
{
"id": 2397,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 1494,
"name": "Access to Biological Collection Data DNA extension",
"type": "model_and_format"
}
},
{
"id": 2398,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 438,
"name": "INSD sequence record XML",
"type": "model_and_format"
}
},
{
"id": 2399,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 114,
"name": "FASTQ Sequence and Sequence Quality Format",
"type": "model_and_format"
}
},
{
"id": 2400,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 262,
"name": "Minimum Information about any (x) Sequence",
"type": "reporting_guideline"
}
},
{
"id": 2401,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 664,
"name": "A Gold Path format",
"type": "model_and_format"
}
},
{
"id": 2402,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 1356,
"name": "Common Metadata Elements for Cataloging Biomedical Datasets",
"type": "reporting_guideline"
}
},
{
"id": 2403,
"recordAssocLabel": "implements",
"linkedRecord": {
"id": 1427,
"name": "DDBJ/ENA/GenBank Feature Table",
"type": "model_and_format"
}
},
{
"id": 13016,
"recordAssocLabel": "deprecates",
"linkedRecord": {
"id": 1973,
"name": "Database of Sequence Tagged Sites",
"type": "repository"
}
},
{
"id": 22767,
"recordAssocLabel": "outputs",
"linkedRecord": {
"id": 5012,
"name": "BioProject identifier",
"type": "identifier_schema"
}
},
{
"id": 22768,
"recordAssocLabel": "outputs",
"linkedRecord": {
"id": 5019,
"name": "BioSamples identifier",
"type": "identifier_schema"
}
},
{
"id": 25400,
"recordAssocLabel": "accepts",
"linkedRecord": {
"id": 1348,
"name": "Generic Feature Format Version 3",
"type": "model_and_format"
}
},
{
"id": 25401,
"recordAssocLabel": "accepts",
"linkedRecord": {
"id": 5048,
"name": "Sequence Read Archive Identifier",
"type": "identifier_schema"
}
},
{
"id": 25563,
"recordAssocLabel": "outputs",
"linkedRecord": {
"id": 5044,
"name": "NCBI Reference Sequence Database Identifier",
"type": "identifier_schema"
}
}
],
"type": "repository"
}
},
"extensions": {
"licence": "https://creativecommons.org/licenses/by-sa/4.0/. Please link to https://fairsharing.org and https://api.fairsharing.org/img/fairsharing-attribution.svg for attribution."
}
}Please note the licence at the end!
We recommend the Altair GraphQL client to test this out.
Last updated
Was this helpful?