Developers

How can we help you?

Note

Note: This resource links cannot be expanded.

A note makes possible to associate some text with an entity denoted by the annotable link.

In BeBanjo land, a note looks like this:

<?xml version='1.0' encoding='utf-8' ?>
<note>
  <text>This is a note</text>
  <link rel="annotable" href="https://movida.bebanjo.net/api/titles/1"/>
</note>

{
  "resource_type": "note",
  "text": "This is a note",
  "self_link": "https://movida.bebanjo.net/api/titles/1/note",
  "annotable_link", "https://movida.bebanjo.net/api/titles/1",
}

Valid attributes

text (required): the text to include in the note.

Resources that support notes

You can add notes to the following resources:

Get a specific note

Any of the resources from the previous section includes the link to its associated note in its XML/JSON representation. For example, consider the Title with id 1.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/titles/1

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/titles/1

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">1</id>
  <!-- ... -->
  <link rel="note" href="https://movida.bebanjo.net/api/titles/1/note"/>
</title>

{
  "resource_type": "title",
  "id": 1,
  // ...
  "note_link": "https://movida.bebanjo.net/api/titles/1/note"
}

You can query the URL associated with its note to retrieve its content:

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/titles/1/note

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/titles/1/note

BeBanjo will return the full XML/JSON of the note if it exists (or a 404 HTTP error response if it doesn’t):

<?xml version='1.0' encoding='utf-8' ?>
<note>
  <text>A note</text>
  <link rel="annotable" href="https://movida.bebanjo.net/api/titles/1"/>
</note>

{
  "resource_type": "note",
  "text": "A new note",
  "self_link": "https://movida.bebanjo.net/api/titles/1/note",
  "annotable_link": "https://movida.bebanjo.net/api/titles/1"
}

Creating a note

To create a note, you just need to POST a proper representation of a note, similar to what you get when fetching one, to the proper endpoint.

To find out the endpoint to which you must POST your payload, you can retrieve the resource first.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/titles/1

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/titles/1

The response contains the URL where you can make a request to create its note:

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">1</id>
  <!-- ... -->
  <link rel="note" href="https://movida.bebanjo.net/api/titles/1/note"/>
</title>

{
  "resource_type": "title",
  "id": 1,
  // ...
  "note_link": "https://movida.bebanjo.net/api/titles/1/note"
}

For example, this POST would create a note for a title (we’ll use curl’s @ option, which reads the data that is to be posted to the URL from a file):

$ cat note.xml

$ cat note.json

<?xml version="1.0" encoding="UTF-8"?>
<note>
  <text>A note</text>
</note>

{
  "text": "A note"
}

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @note.xml "https://movida.bebanjo.net/api/titles/1/note"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @note.json "https://movida.bebanjo.net/api/titles/1/note"

BeBanjo will return the full XML/JSON of the note just created:

<?xml version='1.0' encoding='utf-8' ?>
<note>
  <text>A note</text>
  <link rel="self" href="https://movida.bebanjo.net/api/titles/1/note"/>
  <link rel="annotable" href="https://movida.bebanjo.net/api/titles/1"/>
</note>

{
  "resource_type": "note",
  "text": "A note",
  "self_link": "https://movida.bebanjo.net/api/titles/1/note",
  "annotable_link": "https://movida.bebanjo.net/api/titles/1"
}

Note: only one note can be created per resource. If you attempt to create multiple notes for the same resource, you’ll get an error.

Updating notes

You can update notes issuing a PUT request to the URL of a given note, as the following example illustrates. This example only updates the note’s text.

Note: The note can be updated only if it’s there.

$ cat note.xml

$ cat note.json

<note>
  <text>A new note</text>
</note>

{
  "text": "A new note"
}

Now we send the XML/JSON as the body of a PUT request to the title note’s URL:

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @note.xml "https://movida.bebanjo.net/api/titles/4/note"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X PUT -d @note.json "https://movida.bebanjo.net/api/titles/4/note"

The PUT request would return the updated XML/JSON of the note:

<?xml version='1.0' encoding='utf-8' ?>
<note>
  <text>A new note</text>
  <link rel="self" href="https://movida.bebanjo.net/api/titles/3167189/note"/>
  <link rel="annotable" href="https://movida.bebanjo.net/api/titles/1"/>
</note>

{
  "resource_type": "note",
  "text": "A new note",
  "self_link": "https://movida.bebanjo.net/api/titles/1/note",
  "annotable_link": "https://movida.bebanjo.net/api/titles/1"
}

Deleting notes

The following example shows how to destroy a particular note. Only a DELETE HTTP request to its URL is required:

$ curl --digest -u robot_user:password -X DELETE "https://movida.bebanjo.net/api/titles/4/note"

$ curl --digest -u robot_user:password -H "Accept: application/json" -X DELETE "https://movida.bebanjo.net/api/titles/4/note"

The DELETE request doesn’t return anything, as that note is now gone. If the note does not exist it will return a not found status code.