REST API - Plugixa Image Map

The admin screens are built on a REST API you can use too.

Base: /wp-json/plugixa-image-map/v1

Authentication: a logged-in session with a REST nonce, or an application password. Every route checks the capabilities in Roles and permissions.

Answers are JSON: { "success": true, "data": … }, with meta holding total and pages on lists. Errors carry a code, a message and an HTTP status.

Maps

Method	Route	Does
GET	`/maps`	List. Parameters: `page`, `per_page` (200 at most), `search`, `orderby`, `order`, `view` (`active` or `trash`) and `status` (`draft` or `published`). Any other `status` is refused with 400 instead of being ignored.
POST	`/maps`	Create. Send `title`, and optionally `status` and `doc`.
GET	`/maps/{id}`	One map with its document.
PUT, PATCH	`/maps/{id}`	Update `title`, `status` or `doc`. Send `rev`.
DELETE	`/maps/{id}`	Move to the trash.
POST	`/maps/{id}/restore`	Take out of the trash.
DELETE	`/maps/{id}/purge`	Delete for good, with its history.
POST	`/maps/{id}/duplicate`	Copy as a draft.
POST	`/maps/bulk`	`action` and `ids`. See below.
POST	`/maps/preview`	Returns the HTML for a `doc` without saving it.
GET	`/maps/options`	Published maps, for pickers.

Several maps in one request

POST /maps/bulk takes an action and a list of ids.

`action`	Does	Needs
`publish`	Publishes each map.	Edit
`unpublish`	Sets each map back to draft.	Edit
`trash`	Moves each map to the trash.	Delete
`restore`	Takes each map out of the trash.	Delete
`purge`	Deletes each map for good.	Delete

One request may name 100 maps at most; more is refused with 400, and so are an empty list and an unknown action. The answer lists the ids that were done and those that failed, so one map that cannot be changed does not stop the others.

curl -u "admin:APPLICATION PASSWORD" -X POST \
  -H "Content-Type: application/json" \
  -d '{"action": "publish", "ids": [12, 13, 14]}' \
  https://example.com/wp-json/plugixa-image-map/v1/maps/bulk

Saving safely

Every map has a rev number that goes up by one with each save. Send the rev you loaded with your update. If the map was saved by someone else in the meantime, you get 409 Conflict instead of overwriting their work.

curl -u "admin:APPLICATION PASSWORD" -X PUT \
  -H "Content-Type: application/json" \
  -d '{"rev": 4, "status": "published"}' \
  https://example.com/wp-json/plugixa-image-map/v1/maps/12

The document

doc is the map itself: the picture, the settings and the list of hotspots. Positions are percentages of the picture. Whatever you send is cleaned by the same rules as the editor: unknown keys are dropped, colours and addresses are checked and tooltips are filtered. The answer contains the document as stored.

History and autosave

Method	Route	Does
GET	`/maps/{id}/revisions`	Saved versions.
POST	`/maps/{id}/revisions`	Keep a named checkpoint. Send `label`.
GET	`/maps/{id}/revisions/{revision}`	One version with its document.
POST	`/maps/{id}/revisions/{revision}/restore`	Restore it.
GET / PUT / DELETE	`/maps/{id}/autosave`	Read, store or discard unsaved work.

Import and export

Method	Route	Does
GET	`/maps/{id}/export`	The export file.
POST	`/import`	Import. Send the file’s contents as `file`. A request over 3 MB is refused with 413.
GET	`/import/image-map-pro/sources`	Image Map Pro maps found on this site.
POST	`/import/image-map-pro`	Import one: send `project` or `source_id`. The same 3 MB limit applies.

Other

Method	Route	Does
GET	`/dashboard`	The dashboard’s numbers.
GET, PUT, POST	`/settings`	Read or change the settings. Changing `delete_data_on_uninstall` also needs WordPress’s own `manage_options`.
GET	`/bootstrap`	The current user’s permissions and settings.

Pro routes PRO

Method	Route	Does
POST	`/csv/preview`	Read a CSV and report its rows and problems. A CSV over 1 MB is refused with 413.
POST	`/csv/import`	Make a draft from a CSV. Send `csv`, `title` and `image`.
POST	`/icons`	Add an SVG icon. It is cleaned before it is stored.
GET	`/stats`	A map’s statistics. Parameters: `map`, `days` (7, 30, 90 or 365).
POST	`/stats/hit`	Used by the visitor script. Public, and limited to 20 requests a minute from one address; beyond that the answer is 429.

Recent searches