API
This page describes the API exposed by the Concepts plugin.
Ajax endpoints
The endpoints are standard Wordpress ajax endpoints with "concepts" as the action
.
The API is called upon using the url <domain>/ajax.php
.
Use the following parameters in your requests:
uuid - The object to handle
route - The action to take
Use query parameters for
GET
and form-data forPOST
Routes
Method
Route
Description
GET
show
Reading or retrieving data.
POST
create
Add/Create Concept to site.
POST
delete
Remove/Delete Concept from site.
POST
update
Update Concept on site.
POST
sync
Synchronize Concept to the site.
Parents and parent creation
Concepts are hierarchical which means that they have a parent-child relation to it self. They will therefor depend on its parent to exist in order to set itself as child. To make sure its parent always exist in Wordpress, both create
and update
will first check if its parent exist and try to create it if it doesn't. This behaviour is recursive which means that each "parent creation" will trigger a check for its parent which might trigger a new "parent creation" and so on. Only the needed parents will be checked so if parent is found no further checks will be done further up in the hierarchy.
Synchronizing Concepts
The sync
route combines the CRUD-functionality to perform the task of keeping a concept in sync between Open Content and Wordpress. It will create non existing concepts and update existing ones. Concepts that can't be retrieved from Open Content will be removed for Wordpress if they are found.
Events
We trigger events whenever a certain endpoints cause concepts to be created, updated or deleted. Use our the \Everyware\Concepts\ConceptEvents
to listen to these events.
The listen()
method takes up to three arguments:
The event name (string) that this listener wants to listen to;
A PHP callable that will be executed when the specified event is dispatched;
An optional priority, defined as a positive or negative integer (defaults to 0). The higher the number, the earlier the listener is called. If two listeners have the same priority, they are executed in the order that they were added.
A PHP callable is a PHP variable that can be used by the call_user_func()
function and returns true when passed to the is_callable()
function. It can be a \Closure
instance, an object implementing an __invoke()
method (which is what closures are in fact), a string representing a function or an array representing an object method or a class method.
Once a listener is registered, it waits until the event is notified. In the above example, when the create event is triggered, the MyEventHandler::handle()
method will be called will pass an event which implements Everyware\Concepts\Contracts\ConceptEvent
as the single argument:
The Everyware\Concepts\Contracts\ConceptEvent
event will include the uuid and the Post that triggered the event.
So far, you've seen how PHP objects can be registered as listeners. You can also register PHP Closures as event listeners:
We have also added some other ways to use classes:
The events are handled by Wordpress action hooks. This means that you can use wordpress to handle these events to:
The available hooks are:
ew_concept_created
ew_concept_deleted
ew_concept_updated
Note! Learn more about listening to wordpress actions here
Response
These endpoints have a number of responses depending on the outcome. Every responses comes with "responseCodes" to describe the outcome of the request and any side-effects that might have had. The possible "responseCodes":
ResponseCodes
Description
ALREADY_EXISTS
Is primarily used on create
and indicates that the requested Concept already exists in Wordpress.
INTERNAL_ERROR
The server encountered an unexpected condition with unknown side-effects.
INVALID_ROUTE
The route
value is invalid. Either it doesn't exist or the wrong method is used.
MOVED
Is primarily used on update
and indicates that the requested Concept have been moved in its hierarchical order (Its Parent has changed).
NOT_FOUND_IN_WP
The requested Concept could not be found in Wordpress.
NOT_FOUND_IN_SOURCE
The requested Concept could not be retrieved from Open Content.
PARENT_CREATED
The request resulted in the creation of parents. This can be in direct and indirect relation(parent and/or parents parent).
PARENT_NOT_CREATED
The server encountered an unexpected condition when trying to create a parent. The requested Concept will not keep its parent relation on the site. This will result in a hierarchical miss-match with Open Content.
PARENT_NOT_FOUND_IN_WP
The requested Concepts parent could not be found in Wordpress. This will trigger creation for that Parent.
PARENT_NOT_FOUND_IN_SOURCE
The requested Concepts parent could not be retrieved from Open Content. This pretty much means PARENT_NOT_CREATED
where we know the condition for failing creation.
Show GET
GET
form-data: none
Found
Status Code: 200
Not found
Status Code: 404
Create POST
POST
Created
Status Code: 201
Created as well as one or more parents in the hierarchy
Status Code: 201
Created but parent was not
Status Code: 201
Created but could not retrieve one or more parents from Open Content
Status Code: 201
Not Created since it already exists
Status Code: 409
Not Created since it could not be retrieved from Open Content
Status Code: 424
Not Created because of internal error
Status Code: 500
Delete POST
POST
Deleted
Status Code: 200
Not Deleted because it could not be found in Wordpress
Status Code: 404
Not Deleted because of internal error
Status Code: 500
Update POST
POST
Updated
Status Code: 200
Updated and one or more parents in the hierarchy was created
Status Code: 200
Updated and parent was changed
Status Code: 200
Updated and moved to a newly created parent this might include creation of other parents in the hierarchy
Status Code: 200
Updated but parent was not found in Wordpress and could not be created
Status Code: 200
Updated but could not retrieve one or more parents from Open Content
Status Code: 200
Not updated because it could not be found in Wordpress
Status Code: 404
Not updated because it could not be retrieved from Open Content
Status Code: 424
Not updated because of internal error
Status Code: 500
Sync POST
POST
Synchronized
Status Code: 200
Note! The Concept might have been created, updated or removed as part of the synchronization.
Synchronized and parent was changed
Status Code: 200
Not synchronized because it could not be retrieved from Open Content
Status Code: 424
Most of the errors available for create, update and delete will also be possible to sync.
Last updated
Was this helpful?