Skip to content

Quickstart

Overview

Learn the foundations for using the Giosg REST API, starting with authentication and some endpoint examples.

Let's walk through creating Giosg account, obtaining API token and making your API first request.

Prerequisites

Before you can start using the Giosg APIs, you need to have following:

  1. Giosg account. Don't worry if you don't have one yet.
  2. Giosg API token for authorizing requests.

Obtaining User API token and authenticating

You may create API token in Giosg user interface, more specifically here: https://service.giosg.com/settings/live/company/tokens.

Once you have obtained your API token, define the Authorization HTTP header for your API request to use it. Note that "token word" should be Token when using API token and Bearer when using OAuth2 access token.

Example: Authorization: Token <api token>

Remember that the API token is connected to the user that was used to create the token. This means that if the user is deleted also the token is invalidated. Token will also have same permissions as the associated user so you may also limit tokens permissions per use case.

Authentication to Giosg API's

Authentication to Giosg API's works either with API Token which we just created or by OAuth2 access token. In this tutorial we use API token because it's ease of use.

All Giosg products use same authentication tokens and API conventions, so when you learn one, other should feel familiar also.

You have access to different API's depending on what Giosg products your subscription has enabled.

Once you have obtained your API token, define the Authorization HTTP header for your API request to use it.

Example: Authorization: Token <api token>.

Below are few example for making requests to Giosg API with your API token in place. Replace <api token> with your actual API token.

1
2
3
4
5
6
7
8
9
import requests

API_TOKEN = "<api token>"
url = "https://service.giosg.com/api/v5/users/me"
response = requests.get(url, headers={
    'Authorization': 'Token {}'.format(API_TOKEN)
})
response.raise_for_status()
print(response.json())

1
2
3
4
5
6
7
8
9
const API_TOKEN = "<api token>";
const url = `https://service.giosg.com/api/v5/users/me`;
const response = await fetch(url, {
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(await response.json());

1
2
export GIOSG_API_TOKEN="<api token>"
curl -s -H 'Authorization: Token '$GIOSG_API_TOKEN https://service.giosg.com/api/v5/users/me

Make your first requests!

To test that your API token and code works, lets first fetch current user's (API token owner) information which is always available, no matter what products you have enabled.

Fetching current user's information is simple as making GET request to https://service.giosg.com/api/v5/users/me endpoint.

1
2
3
4
5
6
7
8
9
import requests

API_TOKEN = "<api token>"
url = "https://service.giosg.com/api/v5/users/me"
response = requests.get(url, headers={
    'Authorization': 'Token {}'.format(API_TOKEN)
})
response.raise_for_status()
print(response.json())

1
2
3
4
5
6
7
8
9
const API_TOKEN = "<api token>";
const url = `https://service.giosg.com/api/v5/users/me`;
const response = await fetch(url, {
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(await response.json());

You should be able to run the examples by just copy pasting the code, substituting <api token> with your actual token value and executing the code! Easiest way to start is to run Javascript example in Browsers developer console.

If everything went fine, you should have received your user information and HTTP 200 OK status code. Giosg uses standard HTTP status codes to communicate if the request was successfull or not. If you received HTTP 401 Unauthorized, make sure that you used correct API token.

When you have made the request, note the value in id field of returned JSON. That is your user ID, we will use that on next step!

Updating resources with Giosg API

Let's next try updating our own user object. Updating objects with Giosg API happens with PUT or PATCH requests. All endpoints may not allow PATCH requests but where they are supported, resource can be updated by providing only partial information where as PUT requires all field's to be present in the payload.

Using user ID from previous step, we can make PATCH request to update user.

Replace <user id> with your user ID and <api token> with your API token to run the examples.

If you dont yet know your user ID, please check Make your first requests! above!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import requests

url = "https://service.giosg.com/api/v5/users/{user_id}".format(
    user_id="<user id>"
)
payload = {
    "first_name": "John",
    "last_name": "Doe"
}
response = requests.patch(url, data=payload, headers={
    'Authorization': 'Token {}'.format("<api token>")
})
print(response.json())

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const API_TOKEN = "<api token>";
const USER_ID = "<user id>";
const url = `https://service.giosg.com/api/v5/users/${USER_ID}`;
const response = await fetch(url, {
    method: "PATCH",
    body: JSON.stringify({
        first_name: "John",
        last_name: "Doe"
    }),
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(await response.json());

If everything went fine making above requests, you should have received your own updated user information back and HTTP 200 OK status code.

If you received HTTP 401 Unauthorized, make sure that you used correct API token. If status code was something else, you may refer to standard HTTP status codes and error message provided by the API to figure out what went wrong.

For example if one would try to set too long value to user's first name, API would response with HTTP 400 Bad Request and following JSON error message:

1
{"first_name":["Ensure this field has no more than 32 characters."]}

You may run the example again with your real name to change values back!

Creating and listing resources with Giosg API

Lets next make new resource by using POST method. In this example we create new Team and see how to get a list of resources.

For the the API call we need to know our organization_id. You can find this from current user API endpoint https://service.giosg.com/api/v5/users/me that we already used above.

Remember again to substitute <api token> with your API token and <organization id> with correct organization ID value.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import requests

url = "https://service.giosg.com/api/v6/orgs/{organization_id}/teams".format(
    organization_id="<organization id>"
)
payload = {
    "name": "My first team"
}
response = requests.post(url, data=payload, headers={
    'Authorization': 'Token {}'.format("<api token>")
})
print(response.json())

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
const API_TOKEN = "<api token>";
const ORGANIZATION_ID = "<organization id>";
const url = `https://service.giosg.com/api/v6/orgs/${ORGANIZATION_ID}/teams`;
const response = await fetch(url, {
    method: "POST",
    body: JSON.stringify({
        name: "My first team"
    }),
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(await response.json());

Executing above example creates new Team with name "My first team" and returns the newly created Team resource.

Let's now list all Team resources that our organization has. For this we use exactly same endpoint but with GET method.

1
2
3
4
5
6
7
8
9
import requests

url = "https://service.giosg.com/api/v6/orgs/{organization_id}/teams".format(
    organization_id="<organization id>"
)
response = requests.get(url, data=payload, headers={
    'Authorization': 'Token {}'.format("<api token>")
})
print(response.json())

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const API_TOKEN = "<api token>";
const ORGANIZATION_ID = "<organization id>";
const url = `https://service.giosg.com/api/v6/orgs/${ORGANIZATION_ID}/teams`;
const response = await fetch(url, {
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(await response.json());

Executing above example returns paginated collection of resources, much like example below.

1
2
3
4
5
6
7
8
{
  "next": "https://service.giosg.com/api/v5/examples?cursor=da965a3ea0164c8ab8baef1d4654e2d3",
  "previous": null,
  "results": [
    {"name": "Example Resource 1"},
    {"name": "Example Resource 2"}
  ]
}

That means that for large collections of resources, not all resources are returned in a single response, but the response contains an next and previous URL's that can be used to fetch the next or previous chunks (page) of results. Next and previous fields may also be null if there aren't more resources available.

Deleting resources with Giosg API

As we now know how to list and create objects with Giosg API, let's try to delete the Team we just created. Deleting of resources happens with DELETE method. Deleting only works for single resource at a time so we need to get ID of the Team by listing the resources first. Once you have the Team ID we can proceed on making the deletion request.

Remember again to substitute <organization id>, <team id> and <api token> with correct values.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import requests

url = "https://service.giosg.com/api/v6/orgs/{organization_id}/teams/{team_id}".format(
    organization_id="<organization id>",
    team_id="<team id>"
)
response = requests.delete(url, data=payload, headers={
    'Authorization': 'Token {}'.format("<api token>")
})
print(response.status_code)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
const API_TOKEN = "<api token>";
const ORGANIZATION_ID = "<organization id>";
const TEAM_ID = "<team id>";
const url = `https://service.giosg.com/api/v6/orgs/${ORGANIZATION_ID}/teams/${TEAM_ID}`;
const response = await fetch(url, {
    method: "DELETE",
    headers: {
        "Content-Type": "application/json",
        Authorization: `Token ${API_TOKEN}`,
    },
});
console.log(response.status);

Note that DELETE request does not return content but HTTP 204 No Content if the request was successful. Yoou may now try listing Team resources again to see that the Team was actually deleted.

Conclusion

You now know basics on how to create new resource, retrieve single resource, update a resource and delete resource using Giosg API!

To learn more about Giosg API's and what endpoints are available, please refer to API reference which lists all endpoints, fields or returned resource, possible status codes and much more.

What's next?

Great work! Now as you know the basics on working with Giosg API's, you may want to check out our tutorials for commonly used topics like fetching reporting data, OAuth2 authentication and using some of the visitor side JS API's. You may also want to take a look at our API reference to get understanding whats available!