API resources

Categories

Categories group offers by what they are about, such as sport, art or nature. Use them to build a category filter on your website, or to file new offers.

Everyone with ROLE_HOST can read the categories. Creating, changing and deleting them needs ROLE_SUPER_ADMIN, as in the admin, where they are kept under Einstellungen → Angebote.

The category model

Name
uuid
Type
string
Description
The category's identifier.
Name
name
Type
string
Description
The name of the category.
Name
alias
Type
string
Description
A URL-safe name. Accepted wherever a category is named, as in ?category=sport-bewegung. The category filter on the website uses it in its URLs.

GET/offer-categories

List all categories

Returns every category, ordered by name. The list is not paginated.

To file an offer under a category, send its uuid or alias in the offer's categories.

Anonymous callers can't use this endpoint, but every public offer includes its categories with uuid, name and alias.

Request

GET·/offer-categories

curl https://ferienpass-musterstadt.de/api/offer-categories \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Response

[
  {
    "uuid": "018f2c3d-5a6b-7c7d-8e9f-0a1b2c3d4e19",
    "name": "Kreativ",
    "alias": "kreativ"
  },
  {
    "uuid": "018f2c3d-6b7c-7d8e-9f0a-1b2c3d4e5f20",
    "name": "Natur & Umwelt",
    "alias": "natur-umwelt"
  },
  {
    "uuid": "018f2c3d-4e5f-7a6b-8c7d-9e0f1a2b3c12",
    "name": "Sport & Bewegung",
    "alias": "sport-bewegung"
  }
]

GET/offer-categories/{uuid}

Retrieve a category

Returns one category. The path takes the UUID, not the alias.

Request

GET·/offer-categories/{uuid}

curl https://ferienpass-musterstadt.de/api/offer-categories/018f2c3d-5a6b-7c7d-8e9f-0a1b2c3d4e19 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Response

{
  "uuid": "018f2c3d-5a6b-7c7d-8e9f-0a1b2c3d4e19",
  "name": "Kreativ",
  "alias": "kreativ"
}

POST/offer-categories

Create a category

Creates a category. Super admins only.

Without an alias, one is made from the name: Musik & Tanz becomes musik-tanz. If another category has that alias already, the answer is 409; send an alias of your own then.

Required attributes

Name
name
Type
string
Description
The name, up to 255 characters.

Optional attributes

Name
alias
Type
string
Description
Lowercase letters, digits and hyphens, such as musik-tanz. Anything else is a 422. It must not be the alias of another category (409).

Request

POST·/offer-categories

curl -X POST https://ferienpass-musterstadt.de/api/offer-categories \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Musik & Tanz"}'

Response (201 Created)

{
  "uuid": "0193a4b5-c6d7-7e8f-9a0b-1c2d3e4f5a21",
  "name": "Musik & Tanz",
  "alias": "musik-tanz"
}

PATCH/offer-categories/{uuid}

Update a category

Changes a category's name or alias. Super admins only. The attributes and their rules are the same as for creating a category; send only what you want to change. An empty body is a 422.

Renaming a category keeps its alias. The alias is part of the category filter's URLs on the website and of any link or integration that uses ?category=, so it only changes when you send a new alias. "alias": null makes a new one from the current name.

Request

PATCH·/offer-categories/{uuid}

curl -X PATCH https://ferienpass-musterstadt.de/api/offer-categories/0193a4b5-c6d7-7e8f-9a0b-1c2d3e4f5a21 \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Musik, Tanz & Theater"}'

Response

{
  "uuid": "0193a4b5-c6d7-7e8f-9a0b-1c2d3e4f5a21",
  "name": "Musik, Tanz & Theater",
  "alias": "musik-tanz"
}

DELETE/offer-categories/{uuid}

Delete a category

Deletes a category. Super admins only. Responds with 204 No Content.

While offers are filed under the category, it can't be deleted (409). The message says how many there are. Remove the category from those offers first, by sending their categories without it.

Request

DELETE·/offer-categories/{uuid}

curl -X DELETE https://ferienpass-musterstadt.de/api/offer-categories/0193a4b5-c6d7-7e8f-9a0b-1c2d3e4f5a21 \
  -H "Authorization: Bearer $FEPLI_TOKEN"