REST API - Plugixa Easy Social Share Buttons

Everything the admin app does, it does over REST, under the namespace plugixa-social-share/v1. Two more routes serve your site’s visitors: one returns a post’s counts and one records a click. Pro adds one public route for its email form.

This is the API the plugin itself uses. It is not a separately versioned public API, and the plugin makes no promise that routes, parameters or response shapes stay the same between versions. Pin the plugin version you build against, and test after updating.

Authentication

The plugin adds no authentication of its own. It relies on whatever WordPress provides, and then checks the permissions of the user WordPress identified.

Caller	How
The admin app	The logged-in cookie plus a REST nonce in the X-WP-Nonce header, the normal WordPress way
A script or another system	Any method WordPress accepts for REST requests, such as an application password for an account that holds the permissions below
A visitor’s browser	Nothing. The public routes below need no login and no nonce, because they are called from cached pages

Permissions

Called in the tables below	Capability required
View	plugixa_social_share_view
Edit	plugixa_social_share_edit
Settings	plugixa_social_share_manage_settings
Public	None

Administrators hold every capability. A caller without the capability gets the error code plugixa_social_share_forbidden.

The View and Edit checks pass through the plugixa_social_share_user_can filter. See the Hooks reference.

Response shape

A successful response wraps its payload:

{
  "success": true,
  "data": { }
}

A refusal is a standard WordPress REST error with a code starting plugixa_social_share_, a readable message and an HTTP status. Where one input caused it, data.field names that input.

Code	Status	Meaning
plugixa_social_share_forbidden	401 or 403	The caller lacks the capability
plugixa_social_share_not_found	404	The share set, or the thing asked for, does not exist
plugixa_social_share_set_invalid	400	A share set with no valid network
plugixa_social_share_follow_invalid	400	A follow profile that is not an address on its service
plugixa_social_share_import_missing	404	Nothing to import from that plugin
plugixa_social_share_import_failed	500	A share set could not be created during an import

Routes

Paths are relative to /wp-json/plugixa-social-share/v1.

Settings and catalogues

Method	Route	Needs	What it does
GET	/settings	View	The settings, their defaults, the allowed choices, and which secrets are set. Secret values are never returned
POST	/settings	Settings	Saves settings. Body: settings, an object of keys to change. Keys left out keep their stored value
GET	/catalogue	View	Every network by group, every position, every style, and which networks can show counts
POST	/preview	Edit	Renders an unsaved look with the real renderer. Body: instance (object), post_id (integer, optional). Returns html, sprite, css and the cleaned instance

Share sets

Method	Route	Needs	What it does
GET	/sets	View	Every set, the default set’s number, the next number, the post types and listings a set can be placed on, and a new set’s defaults
POST	/sets	Edit	Creates a set. Body: name, instance, placements
GET	/sets/{id}	View	One set
PUT, PATCH	/sets/{id}	Edit	Changes a set. A field left out keeps its stored value
DELETE	/sets/{id}	Edit	Deletes a set
POST	/sets/{id}/duplicate	Edit	Copies a set, without its placements
GET	/sets/{id}/usage	View	The posts that place the set by hand, for the delete dialog

Every write answers with the whole list of sets as well as the set changed, because saving one set can move a spot out of another. A save also returns moved: the spots it took from other sets.

placements is an object keyed by post type, or by _home and _archive for the blog home and archives. Each value is { "content": "...", "extra": [] }, where content is none, content_top, content_bottom or content_both, and extra lists other position slugs such as float_left or mobile_bar.

Follow buttons

Method	Route	Needs	What it does
GET	/follow	View	The saved profiles and look, and every service on offer
POST	/follow	Edit	Saves the profiles and the look. Body: profiles, a list of { service, value }, and look
POST	/follow/preview	Edit	Renders the row from unsaved profiles and look

Counts and clicks

Method	Route	Needs	What it does
GET	/counts/{post}	Public	A published post’s counts: networks, clicks and total. Numbers below the site’s threshold are left out. An unpublished post returns empty values
POST	/click	Public	Records one share click. Parameters: network (required), post, placement
POST	/counts/recovery	Settings	What unsaved count recovery rules would make of the latest post’s address. Body: recover_http, recover_domain, recover_permalink

/click always answers 204 No Content, whether or not the click was recorded. A click is recorded only when:

• share buttons are switched on,
• the network is one the plugin knows,
• the placement is empty, a registered position, manual, or one a module declared,
• the post exists and is published, and
• the caller is within the limit of 60 clicks a minute.

The limit is kept against a salted hash of the caller’s IP address for one minute. The address itself is never stored.

Analytics

Method	Route	Needs	What it does
GET	/analytics	View	Everything the Share analytics screen draws. Parameter: days, default 30

days is snapped to an offered range: 7 or 30, plus 90 and 365 with Pro PRO. Any other value is treated as 30. The answer holds days, total, previous, series, networks and posts, and with Pro placements PRO.

There is no export route. Pro’s CSV files are made in the browser from this answer.

Link previews

Method	Route	Needs	What it does
POST	/link-previews/preview	Settings	Who prints the tags on this site, and the latest post as its link would look. Body: default_image, an attachment ID, or -1 for the saved one

Import

Method	Route	Needs	What it does
GET	/import	Settings	Each other plugin found, with the plan of what importing it would do
POST	/import/sassy	Settings	Imports from Sassy Social Share
POST	/import/addtoany	Settings	Imports from AddToAny

An import creates its share sets through POST /sets, so the caller needs the Edit permission as well.

Email form PRO

Method	Route	Needs	What it does
POST	/subscribe	Public	Sends the “Save this post” form. Parameters: email, post, consent

It is limited to five requests in ten minutes per caller and answers with a message to show the reader. Its errors:

Code	Status	Meaning
plugixa_social_share_not_found	404	The form is not set up, or share buttons are off
plugixa_social_share_too_many	429	Over the limit
plugixa_social_share_email	400	Not an email address
plugixa_social_share_post	400	The post cannot be saved: not published, protected, or not a type the form goes on
plugixa_social_share_consent	400	The form only subscribes, and the box was not ticked
plugixa_social_share_service	502	The email service could not be reached and no post was sent

Post meta over REST

One post’s own choices are ordinary post meta, exposed through WordPress’s own posts routes on post types that support custom fields. Whoever can edit the post can change them.

Meta key	Type	Edition
_plugixa_share_hide	boolean	Free
_plugixa_share_off	array of position slugs	Free
_plugixa_share_set	integer	Pro PRO
_plugixa_share_pin_image	integer	Pro PRO
_plugixa_share_pin_description	string	Pro PRO
_plugixa_share_pin_nohover	boolean	Pro PRO

Worked example: create a set and place it

Create a set with three networks, below the content on Posts:

curl -X POST https://example.com/wp-json/plugixa-social-share/v1/sets \
  -u "admin:APPLICATION-PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Footer row",
    "instance": {
      "networks": ["facebook", "x", "copy"],
      "template": "pill",
      "layout": "icon"
    },
    "placements": {
      "post": { "content": "content_bottom", "extra": [] }
    }
  }'

The response’s data.item.id is the new set’s number. data.moved lists any spot the save took from another set, and data.items is every set as it now stands.

Read a post’s counts, as a visitor’s browser does:

curl https://example.com/wp-json/plugixa-social-share/v1/counts/123

{
  "success": true,
  "data": {
    "networks": { "reddit": 48 },
    "clicks": { "x": 12, "whatsapp": 9 },
    "total": 48
  }
}

Extending

Add routes of your own on the plugixa_social_share_register_rest_routes action, which passes the namespace. See the Hooks reference.