Difference between revisions of "API Dictionaries"
| (3 intermediate revisions by 2 users not shown) | |||
| Line 7: | Line 7: | ||
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary | [GET] https<nowiki/>://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. | 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. | ||
| Line 15: | Line 17: | ||
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/contacts/contact_type | [GET] https<nowiki/>://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: | ||
| Line 28: | Line 38: | ||
---- | ---- | ||
=IDs or names?= | =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. | + | 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 | [GET] https<nowiki/>://api.dizions.co.uk/v2/clients/id/1/field/id;ethnicity;main_language;school/?resolveIds[]=ethnicity&resolveIds[]=main_language | ||
Latest revision as of 11:02, 6 November 2023
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.
