This chapter describes the step-by-step process of maintaining data in the data model using examples of requests and responses. In the requests we make use of a dummy access token and a non-existing domain name. Please replace these with the values appropriate for your environment. 

5.1 Data Model description

The structure of the data model can be directly requested using the REST API. A GET request with a 'format' query parameter containing 'html' and a valid token will return a description of the data model. See appendix 6.2 for the documentation of the model used in this manual.

This document was requested with the URL

For brevity we will be shortening the access token in further examples.

5.2. Simple data requests

Assuming we're starting out with a completely empty data model, we need to add data before we can continue. Inserting is done by using POST requests. First we're adding some pizzas to the menu by using a POST request to the URL

The body consists of the following JSON:

If this request is completed successfully, the response will contain an X-Resource header:

Note the id in the URL. We can now retrieve the data from the model using a GET request this URL. We can omit the 'format' header, since JSON is the default format, but we need to add our token:

The response contains the information we sent, and the metadata the API added:

Suppose we wanted to change the name of this pizza. We would use the exact same URL, but in stead of a GET we would use a PUT request. In the body we pass any properties that we wish to change:

If the request is processed correctly, we receive another response with a 200 code and the same resource URL. Another GET request will confirm that the information has actually been updated:

Finally, if we wanted to remove the resource, we could use the URL again, but this time with a DELETE request. This request will return no data or resource headers. The success of the request is indicated by the response code. To confirm this, we can test whether the resource has been removed by doing another GET request to the resource URL.

This will return a response code 404, with an additional response header

Note that we can also do a GET request without specifying the id of the resource. The response will consist of all data that the URL refers to. This may return a very large amount of data, and therefore should be used with care.

5.3. Complex data requests

The examples above are for a simple table, but can be extended to more complex situations with related tables. As an example, let's insert an order. Assuming there is a customer in the Deployteq CRM with id 42 and a set of pizzas in our data model, we can compose the following request body:

In this order we set the properties of the order itself, but also immediately add two pizzas to the order. A few important observations apply to the request body:

• We can refer to records in the lookup table containing the pizzas themselves by the value of the field in the lookup table. We created a lookup relation between the pizza field in the orderedpizza table and the name field in the pizza table. By refering to the pizza by name in the order, the data model will create the correct reference.
• We may omit any fields that we don't need, such as the remarks field in the second ordered pizza. Note that the reference field for the  lookup table may also be omitted. The request will succeed, and the record will be inserted, but any attempt to look up the related data will fail.

If we do a POST request to the following URL

the order is added to the customer record.A GET request to the returned resource URL confirms this:

Note how the references to the pizzas have been resolved. Actually, we also could have used the ids of the pizzas while inserting the order. Now that the order has an id that is returned in the X-Resourceheader we can add an orderedpizza record to this order by doing a POST request to the following URL

with the body of the request containing just the orderedpizza record:

The returned X-Resource will point to the inserted orderedpizza record. Updating or deleting the data works as demonstrated earlier. For example, updating the number for one of the ordered pizzas can be done by addressing the ordered pizza in the URL

and updating the properties by PUT-ting the following data:

Deleting this order can be done by using the same URL and sending a DELETE request.

5.4. Restricting selected data

In GET request the total returned set of information may become very large. Therefore it is possible to specify the fields that a GET request should be restricted to, by using one or mode 'fields[]' parameters on the query string. For example, using the following URL

will return a list of all ordered pizzas from all customers, including remarks. Since the 'clang_id' fields are not selected, the complete dataset is anonymized. If no 'fields[]' parameters are present on the query string, all fields will be returned.

It is also possible to filter your result using the 'filter[]' parameters in your URL. For example you want to get all orders for a specific date. This GET request is done by using the following URL

If you only want a specific field returned to you in this request you can combine the 'filter[]' with the 'field[]' parameter.