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

URLHTTP MethodFunzionalità
/service/v1/datasetsGETRetriving datasets
/service/v1/datasets/{DATASET_ID}/metaGETRetrive a dataset by the ID
/service/v1/datasetsPOSTCreate a new dataset
/service/v1/datasets/{DATASET_ID}PUTUpdate a dataset by the ID
/service/v1/datasets/{DATASET_ID}PATCHPatch a dataset by ID. Incremental update
/service/v1/datasets/{DATASET_ID}DELETEDelete a dataset by the ID

Record

URLHTTP MethodFunzionalità
/service/v1/datasets/{DATASET_ID}GETRetrive the records of the dataset with ID
/service/v1/datasets/{DATASET_ID}POSTCreate a new record
/service/v1/datasets/{DATASET_ID}/{RECORD_ID}PUTUpdate a record by the ID
/service/v1/datasets/{DATASET_ID}/{RECORD_ID}PATCHPatch a record by ID. Incremental update
/service/v1/datasets/{DATASET_ID}/{RECORD_ID}DELETEDelete 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 NameDescription
idThe uuid of the dataset or the record
_typeIs the dataset or record type
_statusIs the status of the dataset or the record. Values:
10 : Enabled
-1 : Deleted
_createdon and _modifiedon Timestamp for creation a modification datetime
_createdby and _modifiedbyUser that create or modify a dataset or a record

You can filter the results of a search using the following url parameters:

Nome ParametroDescrizione
qFilter query using mongodb query syntax. See here https://docs.mongodb.com/v3.2/tutorial/query-documents/
textFull text query. Ex: test=farmacie
nearGeo-search. Ex: near=40.23445,18.82726252
sortSort field
directionSort direction. Accepted values:
– “asc” for ascending
– “desc” for discending
statusData 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 nameDescription
_nameDataset name (optional)
_slugThe permalink of the dataset (mandatory)
_descriptionDataset description (optional)
_licenseLicense type of the dataset (optional)
_tagsComma separated dataset tags. Ex: health, government, education
_originThe 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 NameDescription
idThe uuid of the record
_typeFor record the value is “record”
_statusIs the status of the dataset or the record. Values:
10 : Enabled
-1 : Deleted
_createdon and _modifiedon Timestamp for creation a modification datetime
_createdby and _modifiedbyUser that create or modify a dataset or a record

You can filter the results of a search using the following url parameters:

Nome ParametroDescrizione
qFilter query using mongodb query syntax. See here https://docs.mongodb.com/v3.2/tutorial/query-documents/
textFull text query. Ex: test=farmacie
nearGeo-search. Ex: near=40.23445,18.82726252
sortSort field
directionSort direction. Accepted values:
– “asc” for ascending
– “desc” for discending
statusData 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