Best Practices

References to Entities

To make the most of our API, we recommend storing all ids you use locally.

For example, we now have a system for which we want to build an integration, which we use to create projects. In this system, the user now added a Project with the ID "P1337". An event gets triggered that will create a folder in MemoMeister too. It will give you an id and all other requested fields. This id we then save in a 1:1 mapping somewhere locally.

For example, a simple JSON could look like

{
  "P1337": "Zm9sZGVyOjYyN2ZlOTlhMjYxNzNhNDFlNGVlNTc5Mg=="
}

As we now have mapped the internal ID with the MemoMeister ID, we can easily update MemoMeister when something changes in our internal system, e.g., changed the location or the description. We only have to look up which MemoMeister ID we have to use in that mapping. No folder search is required.

From now on, with the folder example, you could fetch the folder with this query:

# Single Folder
query Folder($id: String!) {
  folder(id: $id) {
    id
    name
    description
    # other fields
  }
}

# Multiple Folders at once
query Folders($ids: [String]!) {
  foldersById(ids: $ids) {
    edges {
      node {
        id
        name
        description
        # other fields
      }
    }
  }
}

Similar queries are there for documents, labels, and users too.

Fetching the folder hierarchy

There are multiple ways that could work depending on what you actually need.

If the user needs to interact with it, for example to navigate through the folders, then the best thing would be to request the folders by its parentId like:

query FolderList($parentId: String, $after: String, $first: Int) {
  folders(filter: { parentId: $parentId }, after: $after, first: $first) {
    edges {
      node {
        id
        name
        hasSubfolders
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Where you then fetch the first page in the root level by setting the parentId to null.
If you then need to fetch another page (in case it has one), you set the after attribute with the value from folders.pageInfo.endCursor.
When the user clicks on a folder, you fetch then the first page of the subfolders of that folder by setting the parentId to the id the user clicked on and set after to null.

note

This is actually how we use it in our apps, so the API is optimized for those kind of queries

---

if the goal is primarily to just have all folders and you are ok with building the hierarchy yourself, then you omit the parentId from the above query completely and just fetch one page after the other.

query FolderList($after: String, $first: Int) {
  folders(after: $after, first: $first) {
    edges {
      node {
        id
        name
        parentId
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

tip

This approach is the best when you want to reduce your api calls, as it maximizes the density of the results.