Sylius Media Alt Text: Admin API

Admin API of the Sylius Media Alt Text plugin: reading and writing alt, decorative and altTexts on product, category and avatar images, the replace semantics and the 422 error cases.

Deutsche Version

Back to overview

Sylius Media Alt Text: Admin API

This documentation always describes the latest published version.

The plugin extends the existing image endpoints of the Sylius Admin API; it adds no new routes. This applies to product images, category images and avatar images.

Fields

Field	Type	Read	Write	Description
`alt`	string	yes	no	Resolved text including fallback, as the Storefront outputs it
`decorative`	boolean	yes	yes	Whether the image is marked as decorative
`altTexts`	object (language => text)	yes	yes	All maintained texts, always an object, even when empty

The Admin API always shows what is maintained, even when the output is turned off in the shop.

Writing

PUT /api/v2/admin/products/MUG/images/12
Content-Type: application/ld+json

{
  "type": "main",
  "altTexts": { "en_US": "A blue mug on a table", "de_DE": "Eine blaue Tasse auf einem Tisch" },
  "decorative": false
}

The same fields work with the multipart upload POST /api/v2/admin/products/{code}/images (e.g. altTexts[en_US]=...) and on the endpoints for category images (/api/v2/admin/taxons/{code}/images, with PUT and multipart POST). In Sylius, the avatar image of an administrator (/api/v2/admin/administrators/{id}/avatar-image) only has GET, multipart POST and DELETE, so you set the texts on the POST there.

altTexts replaces the complete set of texts: a language you leave out loses its text. If you omit altTexts from the request entirely, the stored texts stay unchanged. The same applies to decorative.

Error responses

The response is 422 and nothing is saved (the whole request runs in one transaction) for:

Cause	Message or behavior
Language that is not enabled in the shop	`The locale "xx_XX" is not enabled in this shop.`
Text longer than 255 characters	Length validation fails
`altTexts` is not an object or a value is not a string	Type error
`decorative` is not a boolean	`"decorative" must be a boolean.`

Example: reading texts

curl -s https://shop.example.com/api/v2/admin/products/MUG/images/12 \
  -H "Authorization: Bearer $TOKEN" -H 'Accept: application/ld+json'

Besides the Sylius fields, the response contains something like:

{
  "alt": "A blue mug on a table",
  "decorative": false,
  "altTexts": { "en_US": "A blue mug on a table", "de_DE": "Eine blaue Tasse auf einem Tisch" }
}