Icon REST API
Reference
Two REST resources report what the icons of an Icon Theme are made of, without rendering them. Both answer application/xml and application/json, and both take the name query parameter once per icon asked for.
| Resource | Reports the icons of |
|---|---|
| GET /rest/wikis/{wiki}/iconThemes/icons?name={name} | The theme the wiki uses, or the icon set built into the distribution when it has none. |
| GET /rest/wikis/{wiki}/iconThemes/{theme}/icons?name={name} | The theme named in the path. |
The answer holds one icon per name the theme maps and one missingIcons entry per name it does not, in the order they were asked for. An icon carries its name, the iconSetName it came from and the iconSetType, then cssClass on a font theme or url on an image theme:
# Three names, of which one is not in the theme.
curl -H 'Accept: application/json' \
'http://localhost:8080/xwiki/rest/wikis/xwiki/iconThemes/icons?name=add&name=home&name=unknown'{"icons":[
{"name":"add","iconSetType":"FONT","iconSetName":"Font Awesome","cssClass":"fa fa-plus","url":null},
{"name":"home","iconSetType":"FONT","iconSetName":"Font Awesome","cssClass":"fa fa-home","url":null}],
"missingIcons":["unknown"]}The same names against an image theme report a url instead:
curl -H 'Accept: application/json' \
'http://localhost:8080/xwiki/rest/wikis/xwiki/iconThemes/Silk/icons?name=home'{"icons":[{"name":"home","iconSetType":"IMAGE","iconSetName":"Silk","cssClass":null,
"url":"http://localhost:8080/xwiki/resources/icons/silk/house.png?cache-version=1785156334000"}],
"missingIcons":[]}Status codes
| Code | When |
|---|---|
| 200 | The request was answered, whether or not every name asked for was found. |
| 404 | The wiki does not exist, or the theme named in the path does not. |
| 500 | The theme could not be read. |
FAQ
Does a missing icon fall back to another theme?
No. A name the theme does not map is reported in missingIcons, and what to draw instead is the caller's decision.
Why is the url of a font icon null?
A font theme draws its icons from CSS classes, so only cssClass is set. The XML answer leaves the element out altogether rather than returning it empty.
