CakeSlice

API Overview

This guide will give you a general understanding of the Cake Slice API.

Cake Slice follows a subset of the official JSON API specification. However, it differs slightly on how it handles sparse fields and included relationships. You can read more about the spec on the official JSON API website.

The basics

Cake Slice takes a pragmatic approach with it's API. It follows the structure of the official JSON API spec, but diverges in key areas to better deliver a more appropriate set of information to consumers. Here's a basic example:

Request

GET
/v1/attachments/:id
const response = await fetch(
  "https://api.cakeslice.com/v1/attachments/:id",
  {
    headers: {
      "Authorization": `Bearer ${token}`
    }
  }
)

await response.json()

Response

{
  "data": {
    "id": "abc-def-123",
    "type": "attachment",
    "attributes": {
      "filename": "cake.png",
      "height": 1024,
      "width": 512,
      "size": 561744,
      "mimetype": "image/png",
      "tags": [],
      "caption": "a slice of cake with a cherry on top",
      "description": "The image features a slice of cake with a cherry on top, placed on a white plate. The cake is white and appears to be a delicious dessert. The plate is positioned on a dining table, which occupies the majority of the scene. The close-up view of the cake slice and cherry creates a mouth-watering visual, inviting the viewer to indulge in a sweet treat.",
      "state": "previewable",
      "library_id": "def-ghi-321",
      "created_at": "2025-02-09T21:20:58.501Z",
      "updated_at": "2025-02-14T20:11:46.591Z"
    },
    "relationships": {}
  }
}

In the above example, a single attachment resource was requested and delivered. However, this is not all the attributes an attachment can return. Each resource type has a set of default fields it will return as well as an extra set of fields and relationships a consumer can request that will be returned in addition to the default set.

How to request extra fields

Consumers can modify any given request to request extra fields. Given the attachment example above, let's modify it to request a download URL:

Request

GET
/v1/attachments/:id
const response = await fetch(
  "https://api.cakeslice.com/v1/attachments/:id?fields[attachments]=url,iptc",
  {
    headers: {
      "Authorization": `Bearer ${token}`
    }
  }
)

await response.json()

Response

{
  "data": {
    "id": "abc-def-123",
    "type": "attachment",
    "attributes": {
      "filename": "cake.png",
      "height": 1024,
      "width": 512,
      "size": 561744,
      "mimetype": "image/png",
      "tags": [],
      "caption": "a slice of cake with a cherry on top",
      "description": "The image features a slice of cake with a cherry on top, placed on a white plate. The cake is white and appears to be a delicious dessert. The plate is positioned on a dining table, which occupies the majority of the scene. The close-up view of the cake slice and cherry creates a mouth-watering visual, inviting the viewer to indulge in a sweet treat.",
      "state": "previewable",
      "library_id": "def-ghi-321",
      "created_at": "2025-02-09T21:20:58.501Z",
      "updated_at": "2025-02-14T20:11:46.591Z",
      "url": "https://assets.cakeslice.com/...",
      "iptc": { ... }
    },
    "relationships": {}
  }
}

For GET requests, the URL param is fields[resource_name]=field_one,field_two where resouce_name is attachments, organizations, libraries, etc. (notice the pluralization) and the value is a comma separated list extra attributes to include in the response.

You can request extra fields on multiple resource types by specifying multiple field params. As an example: fields[attachments]=exif,iptc&fields[libraries]=something_else.

In addition to requesting extra fields, a consumer of the Cake Slice API can request extra related records. Here's a quick example:

Request

GET
/v1/attachments/:id?include=library
const response = await fetch(
  "https://api.cakeslice.com/v1/attachments/:id?include=library",
  {
    headers: {
      "Authorization": `Bearer ${token}`
    }
  }
)

await response.json()

Response

{
  "data": {
    "id": "abc-def-123",
    "type": "attachment",
    "attributes": {
      "filename": "cake.png",
      "height": 1024,
      "width": 512,
      "size": 561744,
      "mimetype": "image/png",
      "tags": [],
      "caption": "a slice of cake with a cherry on top",
      "description": "The image features a slice of cake with a cherry on top, placed on a white plate. The cake is white and appears to be a delicious dessert. The plate is positioned on a dining table, which occupies the majority of the scene. The close-up view of the cake slice and cherry creates a mouth-watering visual, inviting the viewer to indulge in a sweet treat.",
      "state": "previewable",
      "library_id": "def-ghi-321",
      "created_at": "2025-02-09T21:20:58.501Z",
      "updated_at": "2025-02-14T20:11:46.591Z"
    },
    "relationships": {
      "library": {
        "data": {
            "id": "def-ghi-321",
            "type": "library"
          }
        }
    }
  },
  "included": [
    {
      "id": "def-ghi-321",
      "type": "library",
      "attributes": {
        "name": "Bake Shop",
        "slug": "assets",
        "privacy": "private",
        "organization_id": "jkl-mno-567",
        "created_at": "2025-01-02T21:59:53.475Z",
        "updated_at": "2025-03-17T18:10:11.946Z"
      },
      "relationships": {}
    }
  ]
}

You can request multiple heirarchies of related records in a single request with the following format: include=library.organization,organization.libraries.

What's next?