To help you only get the rows you want you can use pagination. This is done via the "Page" and "Pagesize" variables. All results will also give the maximum number of pages and the start point of a result set. For example, the call shown below will give the 5th and 6th event and let you know the number of pages in the full result.

URL: {GET} /API/WebsiteAPI/V1/EventPublic/
Headers:
X-apikey: <APIKEY>
X-Page: 3
X-PageSize: 2

Resources contain a selection of fields, a list of which can be found against the resource in the resource section. Certain fields are set to be displayed by default: these are designed to make it easier for a simple call, but any field listed in the resource section can be requested using the "Fields" parameter.

URL: {GET} /API/WebsiteAPI/V1/EventPublic/
Headers:
X-apikey: <APIKEY>
X-fields: EventID, Type, webDescription

This will return a list of events with their EventID, type and description.

If the result is over multiple pages the additional field "RN" is provided to assist with pagination.

You can provide a selection of different filters to get the set of data you need. These will all be provided as a comma separated list in the "Filter" parameter, to clarify the comma acts as an 'AND' which allows multiple filters to be issued in one statement. Currently, it is not possible to use the 'OR' conjunction within the filtering statement. A full list of calls and an example, 'Conferences with more than 100 attendees allowed', can be seen below.

A eq 'B' Equal, where value A equals 'B'
A ne 'B' Not equal, where value A is anything but 'B'
A gt '10' Greater than, where value A is greater than '10'
A ge '10' Greater than or equal to, where value A is greater than or equal to '10'
A lt '10' Less than, where value A is less than '10'
A le '10' Less than or equal to, where value A is less than or equal to '10'
A lk 'B*' Like, A starts with 'B', use * for wildcard
A nl '*B' Not Like, A does not end with 'B', use * for wildcard
A not null Is not null, where value A contains a value
A null Is null, where value A does not contains a value

If the value you are filtering on contains an apostrophe, location name for example, you must prefix the apostrophe with a backslash. e.g. locationName eq 'McDonald\'s'

URL: {GET} /API/WebsiteAPI/V1/EventPublic/
Headers:
X-apikey: <APIKEY>
X-filter: type eq Conference, maxAllowed gt 200

To search for commas (,) inside a filter you should wrap the criteria in single quotes (')

URL: {GET} /API/WebsiteAPI/V1/EventPublic/
Headers:
X-apikey: <APIKEY>
X-filter: webDescription eq 'Dinner, Drinks and Dance', maxAllowed gt 50

You can sort the data by fields in ascending (ASC) or descending (DESC) order, this is done via passing a comma separated list in the "Sort" parameter.

URL: {GET} /API/WebsiteAPI/V1/EventPublic/
Headers:
X-apikey: <APIKEY>
X-sort: eventType, eventName asc

In many cases the end user will need to give permission to modify their records. This will mean that the end user will need to be authenticated. This can either be done via a third party authentication service or by using the username and password stored in the system and using an authentication API to get relevant tokens.

The authentication API is designed to work using OAUTH 2.0 methods. However, due to the nature of API and the data held this is limited to two main methods: third party authentication and Access authentication. The resulting tokens are designed to work in the Bearer authorization schema and are valid for as long as the expiry time, provided with the token, states in seconds.

{
    "access_token": "KnkxNxTDdoSQQ9Sk"
    "token_type": "Bearer"
    "expires_in": 7200
    "refresh_token": "eR9br~Tz9uY4M.0o" (Value optional, see the resource section for if this is provided)
}

If using Access stored username and password you will need to provide the username and password to the token endpoint with a grant type of password: we will return a token as above.

URL: {GET} /API/Authentication/v1/Token/
Headers:
X-apikey: <AuthAPIKEY>
X-grant_type: Password (case insensitive)
X-username: Sally@theaccessgroup.com (case insensitive)
X-password: demo(case sensitive)

If Client details are required, as indicated by the resources tab, these will be passed as an authorization header using basic schema.

Client ID: "123456789" (case sensitive)
Client Secret: "987654321" (case sensitive)
Pre base64: 123456789:987654321 (case sensitive)
Authorization: Basic MTIzNDU2Nzg5Ojk4NzY1NDMyMQ== (Base64 encoded)

If the token allows refresh tokens you can use this second token instead of resending the Username and password.

URL: {GET} /API/Authentication/v1/Token/
Headers:
X-apikey: <AuthAPIKEY>
X-grant_type: refresh_token (case insensitive)
x-refresh_token: eR9br~Tz9uY4M.0o (case sensitive)

Once you have a token you can use it to send the relevant request as below:

URL: {GET} /API/WebsiteAPI/v1/ContactPrivate/000001
Headers:
X-apikey: <APIKEY>
Authorization: Bearer KnkxNxTDdoSQQ9Sk (case sensitive)

Possible authentication errors and troubleshooting

This section lists possible error messages returned by the authentication API and likely causes of the error with the associated solution. It is important to note that the error returned will vary depending on whether the developer mode is currently enabled for your application. With developer mode enabled error messages are more descriptive than their non-developer counterparts. In order to set your application to developer mode you need to modify the MetaData.App table by setting the Developer column to include 'DeveloperMode=Yes' - Warning: the developer column also contains other settings relating to the functionality of the application and therefore it is important to keep those intact when updating this field.

Call

/api/Authentication/v1/Token

Error(Dev)

1001 - The API Key did not match

Error(Non-Dev)

1001 - The API you attempted to connect to could not be found

Cause

The header section of your call is either missing an API key or the API key is incorrect

Solution

Make sure that the header section of your call contains the ‘X-apikey’ header and verify that the correct API key is being used in the MetaData.WebAPI table of your database.

Call

/api/Authentication/v1/Tokens

Error(Dev&Non-Dev) -

No error code - The API resource you requested could not be found

Cause -

If no error code is returned in the call response, it suggests that the correct API has not been reached.

Solution -

Make sure that the correct URL is referenced in the call. In this example, the URL in the API call calls a non-existent API ‘Tokens’ rather than ‘Token’

Call

/api/Authentication/v1/Token

Error(Dev)

404 - The authentication currently requires a valid grant type

Error(Non-Dev)

401 - Authentication failed

Cause

The header section of your call is either missing a grant type or the grant type is incorrect.

Solution

Make sure that the headers of your call contain the ‘x-grant_type’ header and check it is set to either ‘password’ or ‘refresh_token’.

Call -

/api/Authentication/v1/Token

Error(Dev)

404 - Please check the username/password

Error(Non-Dev)

401 - This request failed authentication

Cause

Incorrect username or password.

Solution

Ensure that the details of the user you are trying to authenticate with are entered match the values in the dbo.WEBUSERLIST table. Alternatively this can be checked via the front-end by going to Admin -> Web Admin -> Web Users, and checking that the email address and password exist on that form.

Call

/api/Authentication/v1/Token

Error(Dev&Non-Dev)

500 - Could not store AuthToken Details

Cause

This error is caused by an internal server error.

Solution

The cause of this error is difficult to pinpoint. The best place to start investigating the source of an internal server error is to view the tracelog entry associated to it (SELECT TOP 1000 * FROM Diagnostics.TraceLog ORDER BY id desc)

Call

/api/Authentication/v1/Token

Error(Dev)

403 - API does not allow refresh tokens to be used

Error(Non-Dev)

401 - This request could not be authenticated

Cause

This error occurs when trying to make a call with a grant type of refresh_token to an API that does not allow token refreshes.

Solution

To enable token refresh modify the metadata.WebAPI table by changing the value of the AuthAllowRefreshToken column to -1

Any API may use a HMAC signature for validation. We support MD5, SHA256 and SHA512 hash algorithms. If this is used for an API it will be indicated in the resource section for APIs and the secret key will be sent to you by the customer. The HMAC is constructed as below, with spaces removed, followed by an example (MD5 HMAC, secret key: "SecretString").

httpheader:<Fields in HTTP Header (alphabetical order, comma separated)>\n
urlparameters:<Fields in URL parameters (alphabetical order, comma separated)>\n
body:<The content of the body of a request (lower case)>\n
path:<URL without domain and parameters>\n
verb:<HTTP Verb (lower case)>

URL: {GET} /API/APIname/v1/Contact/?D=D&c=3
Headers:
X-b: B
X-a: 1
X-hmackey: f8d411cab3dc7d0f07859b3b09edde4d
Content:
{
    "Title": "Mr"
}
[HMAC message:]
httpheader:x-a=1,x-b=b\nurlparameters:c=3,d=d\nbody:{"title":"mr"}\npath:/apiname/v1/contact/\nverb:get

The use of Entity Tags, known here on as ETags, allows users to cut down on network traffic. This is done by having an ETag which represents the data provided. If an API call is getting data it will be returned with an ETag header, i.e. a representation of the returned resource(s). This ETag can be sent as part of a future call (using the "If-None-Match" HTTP header) to the same object and if the data has not been updated it will return a HTTP Not Modified (304) status, to show that since the last time you read this it has not changed.

Due to the data changing frequently, ETags are linked to the resource(s) returned, including the fields and ordering of records. For example, if you load a contact's full name and you want to display it on each page, you can cache this on the client and only update it if the call to read it comes back as modified.

A matching ETag does not indicate that other fields have not been updated; the Modified field against most data records will indicate the date it was last modified.

If there is a validation failure this will be returned to you in a response with a status of "Information" and will have a list of validation issues in the values field.

Errors do sometimes occur so we've tried to make them as clear as possible to help all involved. The resulting object will have a status of "Error" and the HTTP status will not be OK (200).

Errors have a development message and a production message. This is to ensure that during development of the client you are able to get the most out of the messages and during production the API is secure for you to use.

The API provides support for JSON (preferred) and XML objects being sent to and received from the API. This is done using the standard HTTP headers "Accept" and "Content-Type" and corresponding MIME type "application/json" or "application/xml". Note that, by default, the objects will be read and returned as JSON.

The MIME type used for XML is "application/xml" not "text/xml" as, according to the standard, text/*-MIME types have an US-ascii character set unless otherwise specified in the HTTP headers. This effectively means that any encoding defined in the XML prologue (e.g. <?xml version="1.0" encoding="UTF-8"?>) is ignored. This is, of course, not the expected and desired behaviour.

The first call returns the 3rd and 4th (page 2, page size 2) events where they have the event type is 'Chargeable', ordered ascending by the event name. This is shown in JSON and XML (note that the content-type is left out to avoid confusion).

URL: {GET} /API/WebsiteAPI/V1/EventPublic/
Headers:
X-apikey: <APIKEY>
X-Fields: eventID, eventName, eventType, type
x-Sort: eventName asc
x-filter: eventType eq Chargeable
x-page: 2
x-pagesize: 2

The second call just gets a single record based on a ID number (EVT10046) getting IDnumber, event name and event type.

URL: {GET} /API/WebsiteAPI/V1/EventPublic/EVT10046
Headers:
X-apikey: <APIKEY>
X-Fields: eventID, eventName, eventType

The following two are calls to POST (insert) and PUT (update) a new contact: these will show the possible content types.
Quick note on the difference between POST and PUT.
POST command is not idempotent, when the same POST call is made to a data store multiple times it will take effect each time it is invoked. e.g. using POST twice to insert the same user into the database will attempt to create the same user twice resulting in a duplicate entry
In contrast PUT is idempotent, making multiple duplicate PUT calls to a data store will leave the data source unchanged past the 1st recieved call.

URL: {POST/PUT} /API/WebsiteAPI/V1/ContactPublic
Headers:
X-apikey: <APIKEY>
Content:
[JSON]
{"title":"Mr",
"firstName":"John",
"keyName":"Smith",
"alumni":true,
"doNotContact":false,
"doNotEmail":false,
"doNotMail":false,
"doNotPhone":false,
"emailThirdParty":false,
"mailThirdParty":false,
"phoneThirdParty":false,
"serialNumber":"99999991",
"volunteer":false}

[XML]
<?xml version="1.0" encoding="UTF-8"?> <root>

<alumni>true</alumni>
<doNotContact>false</doNotContact>
<doNotEmail>false</doNotEmail>
<doNotMail>false</doNotMail>
<doNotPhone>false</doNotPhone>
<emailThirdParty>false</emailThirdParty>
<firstName>John</firstName>
<keyName>Smith</keyName>
<mailThirdParty>false</mailThirdParty>
<phoneThirdParty>false</phoneThirdParty>
<serialNumber>99999991</serialNumber>
<title>Mr</title>
<volunteer>false</volunteer>
</root>