Difference between revisions of "API Dictionaries"

From Charitylog Manual
Jump to: navigation, search
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
[[API Details| Go to API overview]]
 +
 
[[File:helpheader_small.png|right]]
 
[[File:helpheader_small.png|right]]
  
 
Many of the values returned by the API are IDs, so there's a selection of dictionaries to get the friendly names.
 
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:
+
You can get all the dictionaries using:
 +
 
 +
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary
 +
 
 +
  
−
[GET] https://api.dizions.co.uk/v2/dictionary (not suggested for general use)
+
This returns a large payload, so is not suggested for general use. A better option is to access the dictionaries for the fields you need, via entity/table_reference. The end points below will return the full list of IDs and friendly names, e.g.
  
−
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<nowiki/>://api.dizions.co.uk/v2/dictionary/organisations/district
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/organisations/district
+
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/referrals/project
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/referrals/project
+
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/contacts/contact_type
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/contacts/contact_type
+
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/branch
 +
 
 +
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/client_type
 +
 
 +
you can get client/record related fields by using the following, however this will only display fields used in projects within your system.
 +
 
 +
[GET] https<nowiki/>://api.dizions.co.uk/v2/clients/selectable_fields
  
 
You can also search for items in the dictionary:
 
You can also search for items in the dictionary:
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/search/referrals/project/SEARCH_TERM
+
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/search/referrals/project/SEARCH_TERM
 +
 
 +
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/search/referrals/referrer/SEARCH_TERM
  
−
[GET] https://api.dizions.co.uk/v2/dictionary/search/referrals/referrer/SEARCH_TERM
+
For Extension Database which are "Select From Option List" or "Radio buttons", there is a dictionary for each field, using the collaboration name displayed on each Extension Database Field:
  
−
For Extension Database which are "Select From Option List" or "Radio buttons", there is a dictionary for each field:
+
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/extension_database/INSERT_API_COLLABORATION_NAME_HERE
−
https://api.dizions.co.uk/v2/dictionary/extension_database/INSERT_API_COLLABORATION_NAME_HERE
 
  
 
----
 
----
 +
=IDs or names?=
 +
For read-only applications, e.g. a reporting dashboard, it may be useful to ask the API for the names of options, instead of the IDs, e.g. "Private Rented" instead of "4" for accommodation. This is referred to as "resolving" the IDs. You can specify individual fields, like this:
 +
 +
[GET] https<nowiki/>://api.dizions.co.uk/v2/clients/id/1/field/id;ethnicity;main_language;school/?resolveIds[]=ethnicity&resolveIds[]=main_language
 +
 +
 +
or all fields, like this:
 +
 +
 +
[GET] https<nowiki/>://api.dizions.co.uk/v2/clients/id/1/field/id;ethnicity;main_language;school/?resolveIds[]=ALL
 +
 +
 +
NB this only applies when GETing data, records must always be created and updated using IDs.

Latest revision as of 11:02, 6 November 2023

Go to API overview

Helpheader small.png

Many of the values returned by the API are IDs, so there's a selection of dictionaries to get the friendly names. You can get all the dictionaries using: 

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


This returns a large payload, so is not suggested for general use. A better option is to access the dictionaries for the fields you need, via entity/table_reference. The end points below will return the full list of IDs and friendly names, e.g. 

[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

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

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

you can get client/record related fields by using the following, however this will only display fields used in projects within your system. 

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

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

For Extension Database which are "Select From Option List" or "Radio buttons", there is a dictionary for each field, using the collaboration name displayed on each Extension Database Field: 

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

IDs or names?

For read-only applications, e.g. a reporting dashboard, it may be useful to ask the API for the names of options, instead of the IDs, e.g. "Private Rented" instead of "4" for accommodation. This is referred to as "resolving" the IDs. You can specify individual fields, like this: 

[GET] https://api.dizions.co.uk/v2/clients/id/1/field/id;ethnicity;main_language;school/?resolveIds[]=ethnicity&resolveIds[]=main_language


or all fields, like this: 


[GET] https://api.dizions.co.uk/v2/clients/id/1/field/id;ethnicity;main_language;school/?resolveIds[]=ALL


NB this only applies when GETing data, records must always be created and updated using IDs.

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