Offer categories
Offer 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 offer 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.
/offer-categoriesList all offer 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.
curl https://example.fepli.eu/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"
}
]
/offer-categories/{uuid}Retrieve an offer category
Returns one category. The path takes the UUID, not the alias.
curl https://example.fepli.eu/api/offer-categories/018f2c3d-5a6b-7c7d-8e9f-0a1b2c3d4e19 \
-H "Authorization: Bearer $FEPLI_TOKEN"
Response
{
"uuid": "018f2c3d-5a6b-7c7d-8e9f-0a1b2c3d4e19",
"name": "Kreativ",
"alias": "kreativ"
}
/offer-categoriesCreate an offer 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 a422. It must not be the alias of another category (409).
curl -X POST https://example.fepli.eu/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"
}
/offer-categories/{uuid}Update an offer category
Changes a category's name or alias. Super admins only. The attributes and their rules are the same as for creating an offer 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.
curl -X PATCH https://example.fepli.eu/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"
}
/offer-categories/{uuid}Delete an offer 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.
curl -X DELETE https://example.fepli.eu/api/offer-categories/0193a4b5-c6d7-7e8f-9a0b-1c2d3e4f5a21 \
-H "Authorization: Bearer $FEPLI_TOKEN"