API Details

From Charitylog Manual
Revision as of 09:54, 5 August 2019 by Rduheaume (talk | contribs) (Single Record Extension Databases)
Jump to: navigation, search
Helpheader small.png

On this page you will find some technical details of the Dizions API that works with the system. This enables you to interact with your data without having to log in to the web interface. It is a RESTful API using JSON over https. For prices, please call the office.


File:API.png


API Authentication

API Groups

API Filters

Selecting Specific Fields Via The API

Creating Records Via The API

Updating Records Via The API

External Referrals To The API

File Uploads Using The API

Extension Databases Via The API

Multiple Record Extension Databases [GET]

Multiple record extension databases work as their own entity. They can be accessed in the API by a combination of their name and ID. Convert the name to lowercase, and replace spaces with underscores. Then separate the name and ID with an underscore. For example, this end point that gets all records for extension database 13, called Staff Disciplinary:

[GET] https://api.dizions.co.uk/v2/extension_database/staff_disciplinary_13

You can also specify which fields you want to select, to make things more efficient. Extension database records can be filtered in the same way as other requests, to get all results for a particular referral you can do this:

[GET] https://api.dizions.co.uk/v2/extension_database/wellcheck_notes_9/referral/2289

Multiple Record Extension Databases [PUT]

To create a new record you need to do a [PUT] request.

[PUT] https://api.dizions.co.uk/v2/extension_database/staff_disciplinary_13

Then add the body:

referral 2289

date_43 2018-11-08

The ID of the new record will be returned.

Multiple Record Extension Databases [POST]

To update a record you also need to supply the ID:

[POST] https://api.dizions.co.uk/v2/extension_database/wellcheck_notes_9/id/17 Then add the POST body in the same way as a PUT request.

Reports

Reporting is based on dimensions and metrics, conceptually similar to an X and Y axis, although metrics are optional. If you pass in a dimension against a group, you will get a breakdown of the number of records in that group. For examplem, this will show you how many clients there are in each district:

[GET] https://api.dizions.co.uk/v2/clients/dimension/district

If you want this further broken down by gender:

[GET] https://api.dizions.co.uk/v2/clients/dimension/district/metric/gender

You can also filter the results in the same way as other [GET] requests:

[GET] https://api.dizions.co.uk/v2/clients/dimension/district/metric/gender/main_disability/7;9/blue_badge_holder/Y

To view a user's completed contacts by day for a range of time, you can do this:

[GET] https://api.dizions.co.uk/v2/done_contacts/dimension/day/date_active/2018-10-01,2018-10-31/user/*USER_ID*

Dictionaries

Many of the values returned by the API are IDs, so there's a selection of dictionaries to get the friendly names. As a (slow and heavy) reference you can get all datadict dictionaries:

[GET] https://api.dizions.co.uk/v2/dictionary (not suggested for general use)

If the dictionary is set up in datadict you can access via api_group/table_reference. The end points below will return the full list of IDs and friendly names.

[GET] https://api.dizions.co.uk/v2/dictionary/organisations/district

[GET] https://api.dizions.co.uk/v2/dictionary/referrals/project

[GET] https://api.dizions.co.uk/v2/dictionary/contacts/contact_type

You can also search for items in the dictionary:

[GET] https://api.dizions.co.uk/v2/dictionary/search/referrals/project/SEARCH_TERM

[GET] https://api.dizions.co.uk/v2/dictionary/search/referrals/referrer/SEARCH_TERM