We use cookies (just for analytics) on this website. If you continue we will assume you are happy with it. ok

BeBanjo

Back to index

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 Movida 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>

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 representation. For example, consider the Title with id 1.

$ curl --digest -u robot_user:password 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>

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

Movida will return the full XML 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>

Creating a note

To create a note, you just need to POST a proper XML 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

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>

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
<?xml version="1.0" encoding="UTF-8"?>
<note>
  <text>A note</text>
</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"

Movida will return the full XML of the note just created:

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

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
<note>
  <text>A new note</text>
</note>

Now we send the XML 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"

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

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

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 -H "Content-Type: application/xml" -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.

Last updated May 07th, 2021.