Managing Entities

How to create and update information with the API

Purple gradient wave Purple wave used to give a visual break between the header and body of the page.

Summary

Getting information out of Youmanage is great, however, the real power comes when you can create and modify data as well.

In this article we'll go over how to create data and the different ways there are to update data...

 

Creating Data

Creating new data in Youmanage is somewhat similar to retrieving information, the main difference is that we'll be sending the data we want to create in the body of the request.

For example, if we want to create a new Company, we can take a look at the API Reference for the Companies endpoint and will see that we need to send requests to https://api.youmanage.co.uk/Companies. However, instead of sending a GET request we want to POST some data to the server.

The API reference will also show the information that it expects to be sent, along with what data types and formats the information is required to be in. It will also give some example data so you can see what the information should look like. It is important to note that the API will only accept request body data that is in the JSON format and any other content types will be rejected.

From this we can construct a request that will look something like this:

curl -X POST --data "{ \"Name\": "Awesome Inc.\", \"Enabled": true }" "https://api.youmanage.co.uk/Companies"

{
  "id": 1,
  "name": "Awesome Inc.",
  "enabled": true
}

If all has gone well you will receive a 201 Created response, which will contain the newly created item along with some additional properties that were generated by the system, such as the Id of the entity.

 

Updating Data

Next up we'll look at updating entities and to do that we need to tell the API what entity we want to update.

Looking at the API reference, you can see that the action expects an additional part in the URL which is usually the Id of the entity. Once you have told the API which entity to update, you need to pick the type of update that best suits your use case;

The API can accept a complete update, whereby you need to send all properties of the Entity in the body of the request. If you don't supply a property the API will assume that it has the value of null.

The other type of update is a partial update whereby you only send the information that you want to update and any properties that you don't specify will remain unchanged. This method can be useful if you are only changing a single property on a very large entity.

Let's take a look at each of these in turn...

 

Complete Update

In order to issue a complete update command, you will need to send a request using the PUT HTTP method to the appropriate url for that endpoint (check the API Reference if you're unsure what that is). We're going to use the Companies endpoint again as an example;

curl -X PUT--data "{ \"Name\": "Really Awesome Inc.\", \"Enabled": true }" "https://api.youmanage.co.uk/Companies/1"

{
  "id": 1,
  "name": "Really Awesome Inc.",
  "enabled": true
}

Excellent, we've managed to update our company name whilst keeping the company enabled which is always handy.

However, if we had made the same request but omitted the enabled property in the request body, we would have had a very different outcome;

curl -X PUT--data "{ \"Name\": "Not So Awesome Inc.\" }" "https://api.youmanage.co.uk/Companies/1"

{
  "id": 1,
  "name": "Not So Awesome Inc.",
  "enabled": false
}

This time around we've made a request but we haven't specified all the information of the entity as we only sent the Name but not the Enabled property.  As a result, the API has taken the default value for that property (which in the case of a boolean is false) and has disabled our company even though we didn't explicitly ask it to. 

 

Partial Updates

A partial update is, as the name would imply, where you only want to update some of the properties of an entity.

Requests to this look very similar to the complete update requests.  However we need to inform the API that we want to do a partial update and use the PATCH HTTP verb when sending our requests. With this verb, we can then only send the properties we wish to change in the body of the request. 

Therefore, continuing on with our example from before we can issue the following request:

curl -X PATCH --data "{ \"Enabled\": true }" "https://api.youmanage.co.uk/Companies/1"

{
  "id": 1,
  "name": "Not So Awesome Inc.",
  "enabled": true
}

In this example, we have sent a PATCH request and have only included data for the Enabled property, which has been updated in the response we have received and in contrast to the complete update, we can see that the Name property has remained unchanged.

 

Deleting Data

The last operation to cover is deleting data. This is very similar to getting a specific record except you would send an HTTP DELETE request instead of a GET request.

For example to delete a Company with an idea of 5 we could issue the following command.

curl -X DELETE -i -H "Authorization: ApiKey {ApiKey}" "https://api.youmanage.co.uk/companies/5"
HTTP/1.1 204 No Content

If all was successful the API will return a 204 No Content response. Note that once data has been deleted it will not be recoverable you should take care to only delete data that is no longer required.

 

We've now covered the methods for creating and managing entities, next up we'll look at how to query collection endpoints and restrict the results by applying filters.

Back to all guides