-May the ghost of Sigmund Freud sit opposite you, smirking, whenever you’re in conversation with your mother.

Use the form on this page to generate a random curse!

For the technically-minded, there is more on the API used to request the curse below.

Curses for every occasion API

The basic URL structure is:

GET api.unokay.com/curses-for-every-occasion/{version}

The current version is v1, so the base URL is:

GET api.unokay.com/curses-for-every-occasion/v1

Operations

The operations on the API are:

• Return all curses
• Return a specific curse based on ID
• Return a random curse
• Return the Black Curse

Return all curses

To return all curses, use the operation curses:

/curses

This will return a JSON document containing all the curses. Here's the first few curses as an example:

{
  "status": 200,
  "message": "Success",
  "response": [
    {
      "ID": "CG-001",
      "category": "Vanity",
      "categoryID": 1,
      "image": false,
      "curse": "May you be wearing your worst pair of pants when the vicar comes for tea."
    },
    {
      "ID": "CG-002",
      "category": "Vanity",
      "categoryID": 1,
      "image": false,
      "curse": "May your best hat get crumpled on the number 49 bus."
    },
    {
      "ID": "CG-003",
      "category": "Vanity",
      "categoryID": 1,
      "image": false,
      "curse": "May you find your left eyebrow deeply embarrassing."
    },
    {
      "ID": "CG-004",
      "category": "Vanity",
      "categoryID": 1,
      "image": false,
      "curse": "May your best foot smell and get bunions."
    },
...

The following details are returned for each curse:

• The ID (the Curtis-Goller index number)
• A description of the category of curse
• An ID for the category
• Whether there is an image associated with the curse (currently, the API doesn't return the image)
• The text of the curse

For safety reasons, the Black Curse is not returned by this operation: It needs to be specifically requested.

Return a specific curse based on ID

For each curse there is a unique ID: The Curtis-Goller index number. This has the format 'CG-nnn'. To select a specific curse by ID, you can include the ID in the curses operation:

/curses/{ID}

For example, /curses/CG-023 will return:

{
  "status": 200,
  "message": "Success",
  "response": {
    "ID": "CG-023",
    "category": "Vanity",
    "categoryID": 1,
    "image": false,
    "curse": "May your favourite cardigan unravel on a tent peg."
  }
}

If you specify an ID which is not found, then the API will return a 404 not found error:

{
  "status": 404,
  "message": "Not found",
  "response": null
}

For safety reasons, it is not possible to select the Black Curse by ID.

Return a random curse

It is possible to select a curse at random from all the curses available. The operation is:

/randomcurse

This operation will always return a curse, selected at random.

For safety reasons, it will not select the Black Curse.

Return the Black Curse

To avoid hot-headed, rash and unskilful cursing, the Black Curse must be selected using its own operation:

/theblackcurse

This operation will always return the Black Curse. Note that Black Curse will be returned string reversed and must be delivered this way.

How does it work?

This API was developed as a proof of concept for delivering REST APIs using .htaccess and PHP.

The .htaccess file uses 2 rewrite rules to reformat the REST API format into a URL which calls a PHP file, together with a number of parameters:

Rule 1

Where an operation has a specific ID, for example: https://api.unokay.com/curses-for-every-occasion/v1/curses/CG-123

then this is translated into: https://api.unokay.com/curses-for-every-occasion/v1/index.php?operation=curses&id=CG-123

using the .htaccess rewrite rule: RewriteRule ^(.*)/(.*)/(.*)/(.*)$ $1/$2/curses.php?operation=$3&id=$4 [NC,NE,QSA,L]

Rule 2

Where an operation doesn't have a specific ID, for example: https://api.unokay.com/curses-for-every-occasion/v1/randomcurse

then this is translated into: https://api.unokay.com/curses-for-every-occasion/v1/index.php?operation=randomcurse

using the .htaccess rewrite rule: RewriteRule ^(.*)/(.*)/(.*)$ $1/$2/curses.php?operation=$3 [NC,NE,QSA,L]

The same rule is used for /randomcurse and /theblackcurse operations.

Future development

Return a random curse for a selected category - for example:

/randomcurse?category=1

would return a random 'Vanity' curse.

Return a list of curses based on a text search - for example:

/curses?text=blood

would return all curses containing the text 'blood'.