The data in API is what you use to send data to the Lamplight servers. Lamplight offers a fairly simple Query interface to request data, which is returned in json format (although we may add alternatives in due course).
You will need an API key and access parameters from Lamplight to access data: these are available to system administrators through the admin menu within Lamplight.
The core API documentation can be found here.
After the introductory sections, the details of how to construct the query are split into sections by type of record: work, organisation, people and workarea. Each section is of the following form:
A brief description of what this does.
The base uri for the request is shown:
https://lamplight.online/api/type/dowhat
As discussed below, type will be something like work, and dowhat something like attend
In the documentation below, parameters highlighted in
A list of the fields returned, plus any additional information
So on to the real stuff...
The base uri to use is https://lamplight.online/api
.
To this uri, you need
to append two parameters, separated by a forward slash (/), which describe
what kind of data you want, and the type of request:
https://lamplight.online/api/what/dowhat
.
Here, what must be work or referral (currently)
and dowhat must be attend or add (currently).
Requests may use GET or POST to provide parameters, should use UTF-8 character encoding, and all parameters should be properly encoded. However, to be corrent you should use POST requests (and the Lamplight_Client does so automatically).
There are three access credentials that are required: your Lamplight ID, a project ID, and your customer API key. These must be provided with the request, either as GET or POST parameters. If you append them as a query string, they must appear after the what and howmany parameters described above.
The parameter names are:
All of these are required. An error response will be returned if these are omitted or incorrect
There is only one other required parameter, and one optional:
json
callback({/*data*/})
you specify. This may be used
in javascript implementations to enable you to process the data once it
is added to the page.
Note that using javascript means that you will inevitably make your access credentials public; in many cases this will not be desirable. We recommend that you set up a simple server proxy if you wish to use javascript, that can append access credentials at the server, and pass returned data straight through.
In some cases you can use custom fields as parameters (for example, to search by 'services offered'. In these cases, field names should use the underscore character instead of spaces, and be lower case.
Currently the only format available is json. A successful request will return
an object with two keys: data
and meta
. data
will
generally hold just an id value for confirmation, and meta
is currently unused
by the datain module but has been retained for future use. For
example:
{ data: 12345, meta:'' }
(White space added for readability). If there is an error, the object returned will be of the form:
{ error: 1001, msg: "An English explanation of what the error code (1001 in this example) means" }
You may add attendees to published work records through the API, providing the correct permissions have been set in Lamplight.
The uri to add someone as attending a work records is
https://lamplight.online/api/work/attend/
Each record returned will have the following fields:
An example showing how to add to multiple work records is available here. From that example you can also see how to add to individual records.
You may create referrals through the API, providing the correct permissions have been set in Lamplight.
The uri to create a new referral is
https://lamplight.online/api/referral/add/
You can also set custom referral fields to be added, where they have been set to be updatable in the system admin section. To add custom field values, send the field name (with spaces replaced by underscores) and valid data.
Each record returned will have the following fields:
An example showing how to add a referral is available here.
From version 1.2 of the API, you may create and update profiles for people or organisations through the API, providing the correct permissions have been set in Lamplight.
Profiles added in Lamplight may be placed in a 'holding list' and will need to be confirmed before they become available for use in Lamplight. This is configurable within the admin section of Lamplight.
The uri to create a new profile for a person is
https://lamplight.online/api/people/add/
Requests to people/add MUST be POSTed. Trying to add using GET will return an error.
role
is the only required parameter. All other parameters
are optional (although if you do not pass any data, Lamplight will return an
error). All parameters need to be enabled within Lamplight (in the admin section)
before they will be accepted by the API. Other parameters match the data that
may be requested through the API. Invalid data will be rejected.
You can also add custom fields, where they have been enabled for updating within Lamplight. The format and approach is the same as when requesting these fields. The field name should be the text of the field, in all lower case, with underscores '_' replacing any spaces. The value should be valid for the field. If the field has options (i.e. a select, checkbox, radio etc) the value should be the text value of the option. For example:
If the record is added successfully, the response will be an object
with a property data
, the value of which will be the ID
of the new profile. If there was an error the object will have properties
error
and msg
An example showing how to add a profile is available here.
The uri to update an existing profile for a person is
https://lamplight.online/api/people/update/
Requests to people/update MUST be POSTed. Trying to update using GET will return an error.
role
and id
are the only required parameters. All other parameters
are optional (although if you do not pass any data, Lamplight will return an
error). All parameters need to be enabled within Lamplight for updating (in the admin section)
before they will be accepted by the API. Other parameters match the data that
may be requested through the API. Invalid data will be rejected.
You can also add custom fields, where they have been enabled for updating within Lamplight. The format and approach is the same as when requesting these fields. The field name should be the text of the field, in all lower case, with underscores '_' replacing any spaces. The value should be valid for the field. If the field has options (i.e. a select, checkbox, radio etc) the value should be the text value of the option. For example:
If the record is updated successfully, the response will be an object
with a property data
, the value of which will be the ID
of the new profile. If there was an error the object will have properties
error
and msg
An example showing how to update a profile is available here.
The uri to add a profile for an organisation is
https://lamplight.online/api/orgs/add/
Requests to orgs/add MUST be POSTed. Trying to add using GET will return an error.
Details for adding organisations is identical to that for people,
except that instead of first_name
and surname
parameters there is a single name
parameter.
The uri to update an existing profile for an organisation is
https://lamplight.online/api/orgs/update/
Requests to orgs/update MUST be POSTed. Trying to update using GET will return an error.
Details for updating organisations is identical to that for people,
except that instead of first_name
and surname
parameters there is a single name
parameter.
If there is an error in your request, the server will return an HTTP 400 code, and the body of the response will contain a json encoded error object. Error codes returned by Lamplight start 10xx.
If you are using the php client, it will add a couple of error codes (starting 11xx):
The php client documentation has more information on retrieving error codes/responses.