DocumentationExperience PlatformTags

Notes endpoint

Last update: Thu May 05 2022 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer

In the Reactor API, notes are textual annotations that you can add to certain resources. Notes are essentially comments on their respective resources. The contents of notes have no impact on resource behavior, and can be used for a variety of of use cases including the following:

  • Providing background information
  • Functioning as to-do lists
  • Passing along resource-usage advice
  • Giving instructions to other team members
  • Recording historical context

The /notes endpoint in the Reactor API allows you to manage these notes programmatically.

Notes can be applied the following resources:

These six types are collectively known as “notable” resources. When a notable resource is deleted, its associated notes are also deleted.

NOTE
For resources that can have multiple revisions, any notes must be created on the current (head) revision. They may not be attached to other revisions.
However, notes may still be read from revisions. In such cases, the API returns only the notes that existed before the creation of the revision. They provide a snapshot of the annotations as they were when the revision was cut. In contrast, reading notes from the current (head) revision returns all its notes.

Getting started

The endpoint used in this guide is part of the Reactor API. Before continuing, please review the getting started guide for important information regarding how to authenticate to the API.

Retrieve a list of notes list

You can retrieve a list of notes for a resource by appending /notes to the path of a GET request for the resource in question.

API format

GET /{RESOURCE_TYPE}/{RESOURCE_ID}/notes
Parameter
Description
RESOURCE_TYPE

The type of resource you are fetching notes for. Must be one of the following values:

  • data_elements
  • extensions
  • libraries
  • properties
  • rule_components
  • rules
RESOURCE_ID
The id of the specific resource whose notes you want to list.

Request

The following request lists the notes attached to a library.

curl -X GET \
  https://reactor.adobe.io/libraries/LBcffea1a38c52408cae2398868625a12d/notes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H "Content-Type: application/vnd.api+json" \
  -H 'Accept: application/vnd.api+json;revision=1'

Response

A successful response returns a list of notes attached to the specified resource.

{
  "data": [
    {
      "id": "NTa40de8d76bfd4e40835830900ce83b7b",
      "type": "notes",
      "attributes": {
        "author_display_name": "John Smith",
        "author_email": "jsmith@example.com",
        "created_at": "2020-12-14T17:51:00.411Z",
        "text": "this is a note on a library"
      },
      "relationships": {
        "resource": {
          "links": {
            "related": "https://reactor.adobe.io/libraries/LBcffea1a38c52408cae2398868625a12d"
          },
          "data": {
            "id": "LBcffea1a38c52408cae2398868625a12d",
            "type": "libraries"
          }
        }
      },
      "links": {
        "resource": "https://reactor.adobe.io/libraries/LBcffea1a38c52408cae2398868625a12d",
        "self": "https://reactor.adobe.io/notes/NTa40de8d76bfd4e40835830900ce83b7b"
      }
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "next_page": null,
      "prev_page": null,
      "total_pages": 1,
      "total_count": 1
    }
  }
}

Look up a note lookup

You can look up a note by providing its ID in the path of a GET request.

API format

GET /notes/{NOTE_ID}
Parameter
Description
NOTE_ID
The id of the note that you want to look up.

Request

curl -X GET \
  https://reactor.adobe.io/notes/NT550b7a17ab304d49ba289a2978d673e5 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H "Content-Type: application/vnd.api+json" \
  -H 'Accept: application/vnd.api+json;revision=1'

Response

A successful response returns the details of the note.

{
  "data": {
    "id": "NT550b7a17ab304d49ba289a2978d673e5",
    "type": "notes",
    "attributes": {
      "author_display_name": "John Smith",
      "author_email": "jsmith@example.com",
      "created_at": "2020-12-14T17:51:10.316Z",
      "text": "this is a note on a property"
    },
    "relationships": {
      "resource": {
        "links": {
          "related": "https://reactor.adobe.io/properties/PR4537ac6f1f204ffd864ec47c4b27c2e8"
        },
        "data": {
          "id": "PR4537ac6f1f204ffd864ec47c4b27c2e8",
          "type": "properties"
        }
      }
    },
    "links": {
      "resource": "https://reactor.adobe.io/properties/PR4537ac6f1f204ffd864ec47c4b27c2e8",
      "self": "https://reactor.adobe.io/notes/NT550b7a17ab304d49ba289a2978d673e5"
    }
  }
}

Create a note create

WARNING
Before creating a new note, keep in mind that notes are not editable, and only way to delete them is to delete their corresponding resource.

You can create a new note by appending /notes to the path of a POST request for the resource in question.

API format

POST /{RESOURCE_TYPE}/{RESOURCE_ID}/notes
Parameter
Description
RESOURCE_TYPE

The type of resource you are creating a note for. Must be one of the following values:

  • data_elements
  • extensions
  • libraries
  • properties
  • rule_components
  • rules
RESOURCE_ID
The id of the specific resource that you want to create a note for.

Request

The following request creates a new note for a property.

curl -X POST \
  https://reactor.adobe.io/properties/PRb25a704c0b7c4562835ccdf96d3afd31/notes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'Content-Type: application/json' \
  -d '{
        "data": {
          "type": "notes",
          "attributes": {
            "text": "this is a note on a property"
          }
        }
      }'
Property
Description
type
(Required) The type of resource being updated. For this endpoint, the value must be notes.
attributes.text
(Required) The text that comprises the note. Each note is limited to 512 Unicode characters.

Response

A successful response return the details of the newly created note.

{
  "data": {
    "id": "NT550b7a17ab304d49ba289a2978d673e5",
    "type": "notes",
    "attributes": {
      "author_display_name": "John Smith",
      "author_email": "jsmith@example.com",
      "created_at": "2020-12-14T17:51:10.316Z",
      "text": "This is a note on a property"
    },
    "relationships": {
      "resource": {
        "links": {
          "related": "https://reactor.adobe.io/properties/PR4537ac6f1f204ffd864ec47c4b27c2e8"
        },
        "data": {
          "id": "PR4537ac6f1f204ffd864ec47c4b27c2e8",
          "type": "properties"
        }
      }
    },
    "links": {
      "resource": "https://reactor.adobe.io/properties/PR4537ac6f1f204ffd864ec47c4b27c2e8",
      "self": "https://reactor.adobe.io/notes/NT550b7a17ab304d49ba289a2978d673e5"
    }
  }
}
recommendation-more-help
12b4e4a9-5028-4d88-8ce6-64a580811743