API
The REST API lets you interact with OpenRecordz from anything that can send an HTTP request.
The domain demo.api.openrecordz.com will be use to illustrate examples given in this forum.
Endpoints
Dataset
URL | HTTP Method | Funzionalità |
---|---|---|
/service/v1/datasets | GET | Retriving datasets |
/service/v1/datasets/{DATASET_ID}/meta | GET | Retrive a dataset by the ID |
/service/v1/datasets | POST | Create a new dataset |
/service/v1/datasets/{DATASET_ID} | PUT | Update a dataset by the ID |
/service/v1/datasets/{DATASET_ID} | PATCH | Patch a dataset by ID. Incremental update |
/service/v1/datasets/{DATASET_ID} | DELETE | Delete a dataset by the ID |
Record
URL | HTTP Method | Funzionalità |
---|---|---|
/service/v1/datasets/{DATASET_ID} | GET | Retrive the records of the dataset with ID |
/service/v1/datasets/{DATASET_ID} | POST | Create a new record |
/service/v1/datasets/{DATASET_ID}/{RECORD_ID} | PUT | Update a record by the ID |
/service/v1/datasets/{DATASET_ID}/{RECORD_ID} | PATCH | Patch a record by ID. Incremental update |
/service/v1/datasets/{DATASET_ID}/{RECORD_ID} | DELETE | Delete a record by ID |
Request format
For POST and PUT requests, the request body must be JSON, with the Content-Type header set to application/json.
You can authenticate your REST API requests using basic HTTP authentication. For example, to create a dataset you must set the URL using your OpenRecordz credentials in the following format:
http://username:password@MY_DOMAIN.api.openrecordz.com/service/v1/datasets
Response format
The response format for all requests is a JSON object.
Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure. When a request fails, the response body is still JSON, but always contains the fields code and error which you can inspect to use for debugging. For example, trying to save an object with invalid keys will return the message.
{"status":500,"code":500,"developerMessage":"\n...\n^","moreInfoUrl":"mailto:info@openrecordz.com"}
Dataset
Retrieving datasets
To retrieve the list of all the datasets of YOUR_DOMAIN :
curl http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets
Example to retrieve the list of all the datasets of the demo domain :
curl http://demo.api.openrecordz.com/service/v1/datasets
The response body is a JSON array containing all the dataset metadata, the user-provided fields and plus the system fields:
[ { "id":"584144f9e4b0c145730f7231", "_slug":"elenco-farmacie", "_description":"Elenco Farmacie del comune Demo", "_type":"dataset", "_status":10, "_createdon":1480672505142, "_createdby":"demo", "_modifiedby":"demo", "_modifiedon":1480672505142 }, ........ ]
The following are the system fields presents in every JSON response:
Field Name | Description |
---|---|
id | The uuid of the dataset or the record |
_type | Is the dataset or record type |
_status | Is the status of the dataset or the record. Values: 10 : Enabled -1 : Deleted |
_createdon and _modifiedon | Timestamp for creation a modification datetime |
_createdby and _modifiedby | User that create or modify a dataset or a record |
You can filter the results of a search using the following url parameters:
Nome Parametro | Descrizione |
---|---|
q | Filter query using mongodb query syntax. See here https://docs.mongodb.com/v3.2/tutorial/query-documents/ |
text | Full text query. Ex: test=farmacie |
near | Geo-search. Ex: near=40.23445,18.82726252 |
sort | Sort field |
direction | Sort direction. Accepted values: – “asc” for ascending – “desc” for discending |
status | Data status. Accepted values: – 10 for enabled – 1 for deleted |
For example, if we wanted to retrieve all the datasets created by the user demo we could do:
curl -G --data-urlencode 'q={"_createdby":"demo"}' http://demo.api.openrecordz.com/service/v1/datasets
For example, if we wanted to search with full text the datasets contains the text “farmacia” we could do:
curl -G --data-urlencode 'text=farmacie' http://demo.api.openrecordz.com/service/v1/datasets
Or by the browser: http://demo.api.openrecordz.com/service/v1/datasets?text=farmacie
Retrieving dataset by ID
To retrieve a dataset detail by ID:
curl http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets/DATASET_ID/meta
Example to retrieve the dataset with ID 584144f9e4b0c145730f7231 of the demo domain :
curl http://demo.api.openrecordz.com/service/v1/datasets/58415f90e4b0c145730f7232/meta
The response body is a JSON object containing the dataset metadata, the user-provided fields and plus the system fields:
{ "id":"584144f9e4b0c145730f7231", "_slug":"elenco-farmacie", "_description":"Elenco Farmacie del comune Demo", "_type":"dataset", "_status":10, "_createdon":1480672505142, "_createdby":"demo", "_modifiedby":"demo", "_modifiedon":1480672505142 }
New dataset
To create a dataset you must do:
curl -H "Content-Type: application/json" -X POST -u YOUR_USERNAME:YOUR_PASSWORD -d '{"_slug":"YOUR_DATASET_SLUG"}' http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets
Below the dataset metadata. The user can add user fields.
Parameter name | Description |
---|---|
_name | Dataset name (optional) |
_slug | The permalink of the dataset (mandatory) |
_description | Dataset description (optional) |
_license | License type of the dataset (optional) |
_tags | Comma separated dataset tags. Ex: health, government, education |
_origin | The original url of the dataset |
For example, to create a dataset with name “Elenco Farmacie” to the domain demo:
curl -H "Content-Type: application/json" -X POST -u demo:demodemo -d '{"_slug":"elenco-farmacie","_description":"Elenco Farmacie del comune MyTest"}' http://mytest.api.openrecordz.com/service/v1/datasets
For example, to create a dataset with name “Elenco Farmacie”, description, and user fields like opening_hours, city, address, country:
curl -H "Content-Type: application/json" -X POST -u demo:demodemo -d '{"_slug":"elenco-farmacie-advanced","_description":"Elenco Farmacie del comune MyTest Advanced","opening_hours":"monday-friday. 9:00 am to 19:00 pm", "city":"Rome","address":"via Torino", "country":"ita"}' http://mytest.api.openrecordz.com/service/v1/datasets
Update dataset by ID
To update a dataset you must do:
curl -H "Content-Type: application/json" -X PUT -u YOUR_USERNAME:YOUR_PASSWORD -d 'ADD_NEW_JSON_HERE' http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets/DATASET_ID
Delete a dataset by ID
To delete a dataset you must do:
curl -H "Content-Type: application/json" -X DELETE -u YOUR_USERNAME:YOUR_PASSWORD http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets/DATASET_ID
Patch a dataset by ID
To update incrementaly a dataset you must do:
curl -H "Content-Type: application/json" -X PATCH -d '{"_slug":"YOUR_DATASET_SLUG"}' -u YOUR_USERNAME:YOUR_PASSWORD http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets/DATASET_ID
Record
Retrieving records
To retrieve the list of all the records of a dataset:
curl http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets/{DATASET_ID}
Example to retrieve the list of all the records of the dataset named “ElencoFarmacie” with id 58415f90e4b0c145730f7232 :
curl http://demo.api.openrecordz.com/service/v1/datasets/58415f90e4b0c145730f7232
The response body is a JSON array containing all the results metadata, the user-provided fields and plus the system fields:
[ { "_phone":"06/51531196", "FARMACIE":"ANNUNZIATELLA II", "INDIRIZZO":"VIA G. CANEVA, 15-17", "ORARI":"continuato", "_idext":"1", "C A P":"142", "_email":"annunziatella@farmacap.it", "MUN":"VIII", "ASL":"C", "FAX":"06/51966215", "DIRETTORE":"PITERA' Antonella", "_type":"record", "_status":10, "_createdon":1505840540774, "_dataset_ref_id":"58415f90e4b0c145730f7232", "_createdby":"emanuele.solizzo8989", "_modifiedby":"emanuele.solizzo8989", "_modifiedon":1505840540774, "id":"59c14d9ce4b0a018d1a63833" },
The following are the system fields presents in every JSON response:
Field Name | Description |
---|---|
id | The uuid of the record |
_type | For record the value is “record” |
_status | Is the status of the dataset or the record. Values: 10 : Enabled -1 : Deleted |
_createdon and _modifiedon | Timestamp for creation a modification datetime |
_createdby and _modifiedby | User that create or modify a dataset or a record |
You can filter the results of a search using the following url parameters:
Nome Parametro | Descrizione |
---|---|
q | Filter query using mongodb query syntax. See here https://docs.mongodb.com/v3.2/tutorial/query-documents/ |
text | Full text query. Ex: test=farmacie |
near | Geo-search. Ex: near=40.23445,18.82726252 |
sort | Sort field |
direction | Sort direction. Accepted values: – “asc” for ascending – “desc” for discending |
status | Data status. Accepted values: – 10 for enabled – 1 for deleted |
For example, if we wanted to retrieve all the records with a fulltext query :
curl -G --data-urlencode 'text=Irene' http://demo.api.openrecordz.com/service/v1/datasets/58415f90e4b0c145730f7232
Retrieving record by ID
To retrieve a record detail by ID:
curl http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets//
Example to retrieve the record with ID 584144f9e4b0c145730f7231 of the dataset “ElencoFarmacie”
curl http://demo.api.openrecordz.com/service/v1/datasets/58415f90e4b0c145730f7232/59c14d9ce4b0a018d1a63834
New record
To add a new record to a dataset you must do:
curl -H "Content-Type: application/json" -X POST -u YOUR_USERNAME:YOUR_PASSWORD -d '' http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets/
Below the dataset metadata. The user can add user fields.
Below an example record:
curl -H "Content-Type: application/json" -X POST -u demo:demodemo -d '{"name":"Andrea","surname":"Rossi", "gender": "M"}' http://mytest.api.openrecordz.com/service/v1/datasets/58415f90e4b0c145730f7232
Update record by ID
To update a record you must do:
curl -H "Content-Type: application/json" -X PUT -u YOUR_USERNAME:YOUR_PASSWORD -d 'ADD_NEW_JSON_HERE' http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets/DATASET_ID/RECORD_ID
Delete a record by ID
To delete a dataset you must do:
curl -H "Content-Type: application/json" -X DELETE -u YOUR_USERNAME:YOUR_PASSWORD http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets/DATASET_ID/RECORD_ID
Patch a record by ID
To update incrementaly a record you must do:
curl -H "Content-Type: application/json" -X PATCH -d '' -u YOUR_USERNAME:YOUR_PASSWORD http://YOUR_DOMAIN.api.openrecordz.com/service/v1/datasets/DATASET_ID/RECORD_ID