Get the 15 most recent projects where you are owner

Context

This example will give you guidelines to:

Read and extract some projects from your portfolio
Filter, resize and order the set of projects you want to get

It can be used in the following scenarios:

Display latest created projects on a dashboarding tool
Trigger synchronization operations on new projects with another project management tool
BI integration

Prerequisites

Before trying out this example, we suggest you to read those guides first:

Example

In this example, we will see how to fetch the 15 latest created projects of your workspace portfolio where you are the owner.

Step 1 - Get projects

First we will get some projects from your portfolio. To do so we need to call the list projects endpoint. This is a paginated endpoint that returns a list of projects, page by page, 10 at a time by default. This endpoint supports ordering and filtering the results, which we will use in the following steps.

curl --request GET \
     --url https://api.airsaas.io/v1/projects/ \
     --header 'Authorization: Api-Key YOUR_API_KEY_HERE' \
     --header 'accept: application/json'

const axios = require('axios').default;

const options = {
  method: 'GET',
  url: 'https://api.airsaas.io/v1/projects/',
  headers: {accept: 'application/json', Authorization: 'Api-Key YOUR_API_KEY_HERE'}
};

axios
  .request(options)
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.error(error);
  });

import requests

url = "https://api.airsaas.io/v1/projects/"

headers = {
    "accept": "application/json",
    "Authorization": "Api-Key YOUR_API_KEY_HERE"
}

response = requests.get(url, headers=headers)

print(response.text)

You will get a JSON result like this, including a maximum of 10 projects:

{
  "count": 123,
  "next": "https://api.airsaas.io/v1/projects/?page=2",
  "previous": null,
  "results": [
    {
      "id": "4bc78756-0171-4667-be0f-4903f5186992",
      "short_id": "ACM-P42",
      "name": "My Project",
      "owner": "2d23a098-a41d-4ea8-92ed-0131ff7ee021",
      "status": "backlog",
      "importance": "life-changing",
      "risk": "low",
      "mood": null,
      "progress": 5,
      "start_date": "2022-08-22",
      "end_date": "2023-06-14",
      "effort": 120,
      "effort_used": 3,
      "budget_capex": 5000,
      "budget_opex": 1000,
      "budget_capex_used": 2000,
      "budget_opex_used": 0,
      "...": "more properties"
    },
    {
      "id": "91284fcb-f46f-41fd-9351-7cb7b464cecc",
      "short_id": "ACM-P12",
      "name": "My Project",
      "owner": "3564d15b-9181-43e0-8456-837097bc66dc",
      "status": "backlog",
      "importance": null,
      "risk": "medium",
      "mood": null,
      "progress": 50,
      "start_date": "2022-09-01",
      "end_date": "2022-12-30",
      "effort": 10,
      "effort_used": 5,
      "budget_capex": 2500,
      "budget_opex": 0,
      "budget_capex_used": 2500,
      "budget_opex_used": 0,
      "...": "more properties"
    },
    {
      "...": "more projects"
    }
  ]
}

Step 2 - 15 latest created projects

To get the 15 latest created projects, we need to:

increase the number of projects returned per page, so that we get 15 in one call to the API
order the results by creation date, descending (the most recent ones on the first page, the oldest ones on the last page)

To increase the number of projects per page, we will use the generic pagination query attribute page_size. To read more on how to use it, read the pagination reference. We will append ?page_size=15 to the query url.

To order the results by creation date, we will use the generic query attribute ordering. Each list endpoint in the API reference that can be ordered supports this attribute, and the fields that can be used to order the results are documented in the ordering description of the endpoint. Have a look at the list projects for an example. In our case, we will append ?ordering=-created_at to the query url (it happens that this is also the default order of the projects list endpoint, so we could have omitted this attribute).

The new url is https://api.airsaas.io/v1/projects/?page_size=15&ordering=-created_at.

Updated code sample:

curl --request GET \
     --url https://api.airsaas.io/v1/projects/?page_size=15&ordering=-created_at \
     --header 'Authorization: Api-Key YOUR_API_KEY_HERE' \
     --header 'accept: application/json'

const axios = require('axios').default;

const options = {
  method: 'GET',
  url: 'https://api.airsaas.io/v1/projects/?page_size=15&ordering=-created_at',
  headers: {accept: 'application/json', Authorization: 'Api-Key YOUR_API_KEY_HERE'}
};

axios
  .request(options)
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.error(error);
  });

import requests

url = "https://api.airsaas.io/v1/projects/?page_size=15&ordering=-created_at"

headers = {
    "accept": "application/json",
    "Authorization": "Api-Key YOUR_API_KEY_HERE"
}

response = requests.get(url, headers=headers)

print(response.text)

Step 3 - Filter projects by owner

We only want the projects where you are the owner, so we need to filter the results. For each list endpoint that can be filtered, the reference page lists all the query parameters that can be used for filtering. For example, the List projects endpoint can be filtered by importance, mood, owner, risk, status and status_is_final. Here we will use the owner parameter.

The owner filter parameter requires to use the UUID of the workspace user you want to filter by. To get only projects where you are the owner, we need to get your UUID. To do so, we will use the Get profile endpoint. This endpoint si useful to get information about yourself and your workspace.

curl --request GET \
     --url https://api.airsaas.io/v1/profile \
     --header 'Authorization: Api-Key YOUR_API_KEY_HERE' \
     --header 'accept: application/json'

const axios = require('axios').default;

const options = {
  method: 'GET',
  url: 'https://api.airsaas.io/v1/profile',
  headers: {accept: 'application/json', Authorization: 'Api-Key YOUR_API_KEY_HERE'}
};

axios
  .request(options)
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.error(error);
  });

import requests

url = "https://api.airsaas.io/v1/profile"

headers = {
    "accept": "application/json",
    "Authorization": "Api-Key YOUR_API_KEY_HERE"
}

response = requests.get(url, headers=headers)

print(response.text)

You will get a response like:

{
    "id": "2d23a098-a41d-4ea8-92ed-0131ff7ee021",
    "given_name": "John",
    "family_name": "Doe",
    "name": "John Doe",
    "initials": "JD",
    "picture": "url...",
    "current_position": "Project Manager",
    "workspace": {
        "id": "e1786260-318d-5cb6-8df8-03966d3d78d6",
        "name": "Acme",
        "slug": "acme",
        "logo": "url..."
    }
}

In this example, the UUID that you need is 2d23a098-a41d-4ea8-92ed-0131ff7ee021.

To only include projects where you are the owner, we need to update the project list query url, and add ?owner=2d23a098-a41d-4ea8-92ed-0131ff7ee021.

The final url of this example is https://api.airsaas.io/v1/projects/?page_size=15&ordering=-created_at&owner=2d23a098-a41d-4ea8-92ed-0131ff7ee021.

Final code

Here is the updated code sample:

curl --request GET \
     --url https://api.airsaas.io/v1/profile \
     --header 'Authorization: Api-Key YOUR_API_KEY_HERE' \
     --header 'accept: application/json'

# Extract user id from response

curl --request GET \
     --url https://api.airsaas.io/v1/projects/?page_size=15&ordering=-created_at&owner=EXTRACTED_USER_ID \
     --header 'Authorization: Api-Key YOUR_API_KEY_HERE' \
     --header 'accept: application/json'

const axios = require('axios').default;

const options = {
  method: 'GET',
  url: 'https://api.airsaas.io/v1/profile',
  headers: {accept: 'application/json', Authorization: 'Api-Key YOUR_API_KEY_HERE'}
};

axios
  .request(options)
  .then(function (response) {
    const userId = response.data.id;
    return axios.requests({
      method: 'GET',
      url: `https://api.airsaas.io/v1/projects/?page_size=15&ordering=-created_at&owner=${userId}`,
      headers: {accept: 'application/json', Authorization: 'Api-Key YOUR_API_KEY_HERE'}
    });
  })
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.error(error);
  });

import requests

headers = {
    "accept": "application/json",
    "Authorization": "Api-Key YOUR_API_KEY_HERE"
}

url_profile = "https://api.airsaas.io/v1/profile"
response_profile = requests.get(url, headers=headers)

user_id = response_profile.json()["id"]

url_projects = f"https://api.airsaas.io/v1/projects/?page_size=15&ordering=-created_at&owner={user_id}"
response_projects = requests.get(url_projects, headers=headers)

print(response_projects.text)