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 for POST

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.

Ex. https://www.example.com/ajax.php?action=concepts&route=show&uuid=123-456-789

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.

use \Everyware\Concepts\ConceptEvents;

$eventHandler = new MyEventHandler(new DependencyClass);
ConceptEvents::listen('create', [$eventHandler, 'handle']);

// Or use one of the predefined methods

ConceptEvents::onCreate([$eventHandler, 'handle']);

The listen() method takes up to three arguments:

1. The event name (string) that this listener wants to listen to;

2. A PHP callable that will be executed when the specified event is dispatched;

3. 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:

use \Everyware\Concepts\ConceptEvents;

class MyEventHandler
{
    // ...

    public function handle(ConceptEvents $event)
    {
        $uuid = $event->getUuid();
        $effectedPost = $event->getPost();

        // ... do something
    }
}

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:

use \Everyware\Concepts\ConceptEvents;

ConceptEvents::onCreate(function(ConceptEvent $event) {
    $uuid = $event->getUuid();
    $effectedPost = $event->getPost();

    // ... do something
});

We have also added some other ways to use classes:

use \Everyware\Concepts\ConceptEvents;

ConceptEvents::onCreate('Foo\MyEventHandler'); // Will by default call the "Foo\MyEventHandler::handle()" method on a callable class.

ConceptEvents::onCreate('Foo\MyEventHandler@customMethod'); // Will call the "Foo\MyEventHandler::customMethod()" method on a callable class.

The events are handled by Wordpress action hooks. This means that you can use wordpress to handle these events to:

use Everyware\Concepts\Contracts\ConceptEvent;

add_action('ew_concept_created', function(ConceptEvent $event) {
    $uuid = $event->getUuid();
    $effectedPost = $event->getPost();

    // Do some stuff with this post
});

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

Ex. https://www.example.com/ajax.php?action=concepts&route=show&uuid=XXX-XXX-XXX

form-data: none

Found

Status Code: 200

{
    "responseCodes": [],
    "data": {
        "uuid": "XXX-XXX-XXX",
        "postId": "<POST_ID>",
        "permalink": "<POST_PERMALINK>",
        "parent": {
            "uuid": "XXX-XXX-XXX",
            "postId": "<POST_ID>",
            "permalink": "<POST_PERMALINK>",
            "parent": {}
        }
    }
}

Not found

Status Code: 404

{
    "responseCodes": [],
    "data": {}
}

Create POST

https://www.example.com/ajax.php?action=concepts&route=create&uuid=XXX-XXX-XXX

Created

Status Code: 201

{
    "responseCodes": []
}

Created as well as one or more parents in the hierarchy

Status Code: 201

{
    "responseCodes": ["PARENT_NOT_FOUND_IN_WP", "PARENT_CREATED"]
}

Created but parent was not

Status Code: 201

{
    "responseCodes": ["PARENT_NOT_FOUND_IN_WP", "PARENT_NOT_CREATED"]
}

Created but could not retrieve one or more parents from Open Content

Status Code: 201

{
    "responseCodes": ["PARENT_NOT_FOUND_IN_WP", "PARENT_NOT_FOUND_IN_SOURCE"]
}

Not Created since it already exists

Status Code: 409

{
    "responseCodes": ["ALREADY_EXISTS"]
}

Not Created since it could not be retrieved from Open Content

Status Code: 424

{
    "responseCodes": ["NOT_FOUND_IN_SOURCE"]
}

Not Created because of internal error

Status Code: 500

{
    "responseCodes": ["INTERNAL_ERROR"]
}

Delete POST

https://www.example.com/ajax.php?action=concepts&route=delete&uuid=XXX-XXX-XXX

Deleted

Status Code: 200

{
    "responseCodes": []
}

Not Deleted because it could not be found in Wordpress

Status Code: 404

{
    "responseCodes": ["NOT_FOUND_IN_WP"]
}

Not Deleted because of internal error

Status Code: 500

{
    "responseCodes": ["INTERNAL_ERROR"]
}

Update POST

https://www.example.com/ajax.php?action=concepts&route=update&uuid=XXX-XXX-XXX

Updated

Status Code: 200

{
     "responseCodes": []
}

Updated and one or more parents in the hierarchy was created

Status Code: 200

{
    "responseCodes": ["PARENT_NOT_FOUND_IN_WP", "PARENT_CREATED"]
}

Updated and parent was changed

Status Code: 200

{
    "responseCodes": ["MOVED"]
}

Updated and moved to a newly created parent this might include creation of other parents in the hierarchy

Status Code: 200

{
    "responseCodes": ["PARENT_NOT_FOUND_IN_WP", "PARENT_CREATED", "MOVED"]
}

Updated but parent was not found in Wordpress and could not be created

Status Code: 200

{
    "responseCodes": ["PARENT_NOT_FOUND_IN_WP", "PARENT_NOT_CREATED"]
}

Updated but could not retrieve one or more parents from Open Content

Status Code: 200

{
    "responseCodes": ["PARENT_NOT_FOUND_IN_WP", "PARENT_NOT_FOUND_IN_SOURCE"]
}

Not updated because it could not be found in Wordpress

Status Code: 404

{
    "responseCodes": ["NOT_FOUND_IN_WP"]
}

Not updated because it could not be retrieved from Open Content

Status Code: 424

{
    "responseCodes": ["NOT_FOUND_IN_SOURCE"]
}

Not updated because of internal error

Status Code: 500

{
    "responseCodes": ["INTERNAL_ERROR"]
}

Sync POST

https://www.example.com/ajax.php?action=concepts&route=sync&uuid=XXX-XXX-XXX

Synchronized

Status Code: 200

{
     "responseCodes": []
}

Note! The Concept might have been created, updated or removed as part of the synchronization.

Synchronized and parent was changed

Status Code: 200

{
    "responseCodes": ["MOVED"]
}

Not synchronized because it could not be retrieved from Open Content

Status Code: 424

{
    "responseCodes": ["NOT_FOUND_IN_SOURCE"]
}

Most of the errors available for create, update and delete will also be possible to sync.