Status of the update API
To synchronize hPSCreg with other databases we provide a JSON API to create cell line names. You can also change cell lines with the update API (described here). Currently, the update API only works for a selected number of fields of high importance. We will keep improving the API and add more fields. The API will only receive backwards compatible changes. If you just want to do onetime analysis, you might want to use our Export API.
Please tell us when you implement anything with any of the APIs, giving information what parts/fields you use how. This way we can keep this in mind when making changes and inform you about upcoming versions.
General workflow when updating cell lines
When you want to make changes to a cell line you should GET the JSON of the cell line first, check the data you might overwrite and make your changes in the JSON. You can then POST the changed JSON to the API.
We use HTTP (Basic) Authentication (over https). This is optional when getting cell line data, but can give more information about cell lines you have access to. For updates it is mandatory to authenticate as an hPSCreg user with edit access to the cell line.
How to get a cell line
You can get a the cell line BCRTi001-A with:
This returns a JSON object like this (excerpt):
{
"name": "BCRTi001-A",
"type": "i",
"type_name": "hiPSC",
"alternative_names": [
"P01-1"
],
"biosamples_id": "SAMEA5889524",
"donor": {
"id": 851,
"biosamples_id": "SAMEA5889529",
"disease_flag": true,
"diseases": [
{
"id": 297,
"affected": true,
"purl": "http:\/\/purl.obolibrary.org\/obo\/DOID_13374",
"purl_name": "fibrodysplasia ossificans progressiva"
}
]
},
"institutions": [
{
"id": 492,
"name": "Berlin-Brandenburg Center for Regenerative Therapies",
"acronym": "BCRT",
"role": "Generator"
}
],
…
}
How to update a cell line
You should get the current data for the cell line with a GET request first and check that your are not overwriting anything important. You should also use the test server first to test your code.
With a request like this you update a cell line
POST
https://hpscreg.eu/api/cell-line/v0/BCRTi001-A
{
"name": "BCRTi001-A",
"edit_comment": "something to tell the cell line data validator",
"public_notes": "this can include public information"
}
Some fields are read-only. In the example these are the name and id. Regardless what you send, they will not change. Other fields like the biosamples_id can not be changed once set.
Fields that are not sent with the JSON are always left untouched. The values in the database will not change with the update. If you need to remove the data for a field you need to add it to the JSON with a value of null. Note that this behavior might need special handling with your libraries. See for example the usage of JSONObject.NULL in Java. This behavior makes it possible to add more fields later in a backwards compatible way.
The official documentation for all fields is only available in the actual edit form (the HTML viewed in the browser). In order to find the fields you are interested in you need to GET a cell line where these fields are already set. You can also use the test server to make and test changes there.
Not all fields are implemented. Please contact us if you have specific fields you want and tell about the project or import/export you are currently trying to do.
Test Server
Especially when making changes with a script, you should test your code against the test server first. The test server is available at https://test.hpscreg.eu. This server should run the same code as the production server, but is using a different (test) database.
Export API
As explained in Status of the API we currently can't provide all fields in the stable update API. When you just want to get cell line date for onetime analyzation you can use our unstable export API.
This export output can change at any time when changes are made to the hPSCreg code. When you want a stable API, please use the update API described above and/or contact us with your specific needs.
You can get JSON data for the cell line BCRTi001-A with:
The … are not part of the actual output
and indicate that there will be more in the actual output.
{
"id": "1405",
"status": {
"submitted": true,
"validated": true,
"certified": false,
"withdrawn": false
},
"name": "BCRTi001-A",
"alternate_name": [
"P01-1"
],
"databases": [
{
"database": {
"name": "Cellosaurus",
"description": "Cellosaurus - a knowledge resource on cell lines",
},
"id_in_database": "CVCL_9S03",
"url_in_database": "https:\/\/www.cellosaurus.org\/CVCL_9S03"
}
],
"type_id": "1",
"type_name": "hiPSC",
"biosamples_id": "SAMEA5889524",
"donor": {
"id": 851,
"biosamples_id": "SAMEA5889529",
"databases": [
{
"database": {
"name": "BioSamples",
"description": "database of sample descriptions",
},
"id_in_database": "SAMEA5889529",
"url_in_database": "https:\/\/www.ebi.ac.uk\/biosamples\/samples\/SAMEA5889529"
}
],
"gender": "male",
"disease_flag": true,
"diseases": [
{
"affected": true,
"purl": "http:\/\/purl.obolibrary.org\/obo\/DOID_13374",
"purl_name": "fibrodysplasia ossificans progressiva",
"variants": [
{
"type": "variant",
"gene": {
"database_id": "90",
"database_name": "entrez",
"name": "ACVR1",
"url": "http:\/\/www.ncbi.nlm.nih.gov\/gene\/90",
},
"chromosome_location": "2q24.1",
"zygosity_status": "heterozygous",
"dbsnp_id": "rs121912678",
"publication_pmid": "27345784"
}
]
}
]
},
…
}