Difference between revisions of "API Details"

From Charitylog Manual
Jump to: navigation, search
(→‎Filters)
(→‎API Entities)
 
(87 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[File:helpheader_small.png|right]]
 
[[File:helpheader_small.png|right]]
  
−
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.
+
The API enables technical users capable of writing their own applications to [[Integrations|integrate]] with their Charitylog or Crossdata instance without having to log in to the web interface. It is a RESTful API using JSON over https. For prices, please call the office.  To enable API users please see [[Users#3rd_Party_System_Access|Users]].
  
 +
=General Concepts=
 +
[[Why_use_an_API]]
  
−
[[File:API.png]]
+
[[API Dictionaries]]
−
 
 
  
 
[[API Authentication]]
 
[[API Authentication]]
  
−
[[API Groups]]
+
=API Entities=
−
 
+
The API is based around various entities. To avoid breaking changes, the names in the API are fixed. If you are a developer talking to end users, it's useful to know that many features have different names in the web application, particular because many features can be renamed by a local admin.
−
[[API Filters]]
 
  
−
=Selecting Specific Fields=
+
{| class="wikitable" style="margin:auto"
−
When you hit an endpoint, a range of default fields are automatically returned. If you want something that isn't default, or you want to return less data to speed things up, you can pick the fields to be returned. In the case of referrals or clients you can also return any single record extension databases. Use /field/ with semicolon separated field names to choose the fields you want to return.
+
|-
 +
! API name !! Description !! Renamable in web app? !! Typical names in web app
 +
|-
 +
| [[API_Classification_Codes|classification_codes]] || A tiered coding system used to classify done_contacts and referrals|| Y || Classification code, enquiry codes
 +
|-
 +
| [[API_clients|clients]] || Organisations/people that are people, e.g. clients, staff volunteers etc. || Y || Clients, Service Users, Staff, Volunteers
 +
|-
 +
| [[API_clinics|clinics]] || Group Activities || N || Clubs and Clinics
 +
|-
 +
| [[API_done_contacts|done_contacts]] || Completed actions || N || Contacts
 +
|-
 +
| [[API_due_contacts|due_contacts]] || Outstanding actions that typically make up the Action List in the web application || N || Outstanding actions
 +
|-
 +
| [[API:_Extension_Databases| extension_databases]] || Used to create your own data structures for forms etc || N || Extension Databases
 +
|-
 +
| [[API_external_referrals|external_referrals]] || Referrals collected externally, e.g. a self-referral form on your website || N || Inbound Referrals
 +
|-
 +
| [[Project_Set_Up|project]] || A service your organisation provides  || Y || Project, Service, Department
 +
|-
 +
| [[API_referrals|referrals]] || Groups of done_contacts and due_contacts || Y || Referrals, Cases, Enquiries
 +
|-
 +
| [[API_relationships| relationship_details]] || Relationships between 2 people, e.g. parent, social worker, carer etc || N || Relationships
 +
|-
 +
| [[API_schedules|schedules]] || Roster job cards || N || Jobs cards is not renamable, but the workers are, e.g. Home Helper Job Cards, Support Worker Job Cards etc
 +
|-
 +
| [[Referral_Templates#The_Stages.2FStatuses|stage]] || A stage on a template, e.g. Initial Assessment || N || Stage
 +
|-
 +
| status || A broad grouping of a stage, e.g. Being Supported, Not For Reports etc || N || Status
 +
|-
 +
| [[Referral_Templates|template]] || A workflow, e.g. a collection of stages to guide you through a case || N || Template
 +
|-
 +
| [[API_workers|workers]] || People who work on schedules || Y || Home Helpers, Support Workers, Carers
 +
|}
  
−
'[GET] https://api.dizions.co.uk/clients/field/id;surname;website_photo_consent
+
=Other=
  
−
The API can tell you which fields are available by appending /selectable_fields to the group.
+
[[API: File Uploads| File Uploads]]
  
−
[GET] https://api.dizions.co.uk/v2/clients/selectable_fields
+
=Reading data (GETs)=
  
−
[GET] https://api.dizions.co.uk/v2/workers/selectable_fields
+
[[API Filters]]
−
 
 
−
[GET] https://api.dizions.co.uk/v2/referrals/selectable_fields
 
−
 
 
−
[GET] https://api.dizions.co.uk/v2/due_contacts/selectable_fields
 
−
 
 
−
[GET] https://api.dizions.co.uk/v2/done_contacts/selectable_fields
 
−
 
 
−
[GET] https://api.dizions.co.uk/v2/schedules/selectable_fields
 
−
 
 
−
=Creating Records=
 
−
To create a record you need to do a [PUT] request, with fields in the body. Many of these will have a selection of mandatory fields.
 
−
 
 
−
Create a client:
 
−
 
 
−
[PUT] https://api.dizions.co.uk/v2/clients
 
−
 
 
−
Create a client by an external ID (e.g a reference to the client in another system):
 
−
 
 
−
[PUT] https://api.dizions.co.uk/v2/clients/external_id/EXTERNAL_ID
 
−
 
 
−
Create a referral (Record a Contact):
 
−
 
 
−
[PUT] https://api.dizions.co.uk/v2/referrals
 
−
 
 
−
Create a due contact (incomplete action) for a referral:
 
−
 
 
−
[PUT] https://api.dizions.co.uk/v2/due_contacts/referral/REFERRAL_ID
 
−
 
 
−
=Updating Records=
 
−
To update records you need to use the [POST] method, with fields in the body. There will be some mandatory fields and some fields that need a value if present.
 
−
 
 
−
Update a client:
 
−
 
 
−
[POST] https://api.dizions.co.uk/v2/clients/id/CLIENT_ID
 
−
 
 
−
Most of the fields are the same fields available via GET, such as name, address and demographic details. In addition to it, relationships can also be created with these fields in the body: id_second (the id number of the related person), relationship_first_to_second and relationship_second_to_first (see /dictionary/relationships), and optionally, relationship_first_to_second_carer and relationship_second_to_first_carer (see /dictionary/carer_relationships)
 
−
 
 
−
Update a referral:
 
−
 
 
−
[POST] https://api.dizions.co.uk/v2/referrals/id/REFERRAL_ID
 
−
 
 
−
Update due contact
 
−
 
 
−
[POST] https://api.dizions.co.uk/v2/due_contacts/id/CONTACT_ID
 
−
 
 
−
Update done contact, or complete due contact (complete by completing the start_date and end_date in the body)
 
−
 
 
−
[POST] https://api.dizions.co.uk/v2/done_contacts/id/CONTACT_ID
 
−
 
 
−
=External Referrals=
 
−
External Referrals are held in a staging area, to be imported or rejected by the system administrator.
 
−
 
 
−
[PUT] https://api.dizions.co.uk/v2/external_referral
 
−
 
 
−
The org_type_id, surname and description fields must be passed as a minimum. Most optional fields are any field from the client endpoint, with 1 notable exception: project. Including project will save the user who processes the referrals from having to select it each time they import.
 
−
 
 
−
=File Uploads=
 
−
You can upload files against clients and referrals, these can only be uploaded to Amazon S3.
 
−
 
 
−
[POST] https://api.dizions.co.uk/v2/clients/id/CLIENT_ID/uploads
 
−
 
 
−
[POST] https://api.dizions.co.uk/v2/referrals/id/REFERRAL_ID/uploads
 
−
 
 
−
In the body you'll need the files along with user_visibility and group_visibility settings which are IDs (comma separated if there's more than one)
 
−
 
 
−
=Single Record Extension Databases=
 
−
As mentioned previously, for referrals and clients you can select single record extension database data, or filter by these values. To expose these fields to the API you need to edit that field in the front end, setting Allow collaborator API access? to Yes and choosing a suitable Name to share with collaborators. You can then reference that extension database field by the collaborator name.
 
−
 
 
−
=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
+
[[API: Selecting Specific Fields| Selecting Specific Fields]]
  
−
To view a user's completed contacts by day for a range of time, you can do this:
+
[[API: Reporting| Running Reports]]
  
−
[GET] https://api.dizions.co.uk/v2/done_contacts/dimension/day/date_active/2018-10-01,2018-10-31/user/*USER_ID*
+
=Writing data (POSTs and PUTs)=
 +
[[API: Creating Records| Creating Records]]
  
−
=Dictionaries=
+
[[API: Updating Records| Updating Records]]
−
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)
+
[[API: External Referrals| External Referrals]]
  
−
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.
+
=Making the most of your data=
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/organisations/district
+
[[Excel Power Query| Getting Started with Power Query with Excel]]
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/referrals/project
+
[[Power BI with Power Query| Getting Started with Power Query in Power BI Desktop]]
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/contacts/contact_type
+
[[Power Query - How to's| How to achieve more with Power Query]]
  
−
You can also search for items in the dictionary:
+
=Purchasing and getting started=
 +
[[API:_purchasing| Purchasing]]
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/search/referrals/project/SEARCH_TERM
+
[[Working_with_existing_API_partners| Working with existing API partners]]
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/search/referrals/referrer/SEARCH_TERM
+
[[API:_Sample_Calls| Sample Calls]]

Latest revision as of 09:21, 15 August 2024

Helpheader small.png

The API enables technical users capable of writing their own applications to integrate with their Charitylog or Crossdata instance without having to log in to the web interface. It is a RESTful API using JSON over https. For prices, please call the office. To enable API users please see Users.

General Concepts

Why_use_an_API

API Dictionaries

API Authentication

API Entities

The API is based around various entities. To avoid breaking changes, the names in the API are fixed. If you are a developer talking to end users, it's useful to know that many features have different names in the web application, particular because many features can be renamed by a local admin.

API name Description Renamable in web app? Typical names in web app
classification_codes A tiered coding system used to classify done_contacts and referrals Y Classification code, enquiry codes
clients Organisations/people that are people, e.g. clients, staff volunteers etc. Y Clients, Service Users, Staff, Volunteers
clinics Group Activities N Clubs and Clinics
done_contacts Completed actions N Contacts
due_contacts Outstanding actions that typically make up the Action List in the web application N Outstanding actions
extension_databases Used to create your own data structures for forms etc N Extension Databases
external_referrals Referrals collected externally, e.g. a self-referral form on your website N Inbound Referrals
project A service your organisation provides Y Project, Service, Department
referrals Groups of done_contacts and due_contacts Y Referrals, Cases, Enquiries
relationship_details Relationships between 2 people, e.g. parent, social worker, carer etc N Relationships
schedules Roster job cards N Jobs cards is not renamable, but the workers are, e.g. Home Helper Job Cards, Support Worker Job Cards etc
stage A stage on a template, e.g. Initial Assessment N Stage
status A broad grouping of a stage, e.g. Being Supported, Not For Reports etc N Status
template A workflow, e.g. a collection of stages to guide you through a case N Template
workers People who work on schedules Y Home Helpers, Support Workers, Carers

Other

File Uploads

Reading data (GETs)

API Filters

Selecting Specific Fields

Running Reports

Writing data (POSTs and PUTs)

Creating Records

Updating Records

External Referrals

Making the most of your data

Getting Started with Power Query with Excel

Getting Started with Power Query in Power BI Desktop

How to achieve more with Power Query

Purchasing and getting started

Purchasing

Working with existing API partners

Sample Calls

Retrieved from ‘https://wiki.dizions.co.uk/index.php?title=API_Details&oldid=18507’