Endpoints

Under the hood, the endpoint path will be used to create a ProcessWire URL hook. All URL hook features are supported.

Each endpoint listener must either return a Response object or throw an ApiException to halt the process and respond with an error.

INFO

By default, all the request methods are denied, except for OPTIONS. You must add listeners for each request method you want to allow. Requests with disallowed methods will be denied with a 405 response that includes an Allow header listing the permitted methods.

The OPTIONS method is always allowed for existing endpoints and will result in an empty response with a status code of 200. The response includes an Allow header listing the permitted methods.

The supported listeners are:

• get()
• post()
• head()
• put()
• patch()
• delete()

Like an API instance or service, an endpoint can also contain request hooks. Read more about request hooks.

Example endpoint

Call addEndpoint() in the service init() method and pass the path you want to listen to.

use PwJsonApi\ApiException;

$this->addEndpoint('/user')
  // Handle GET request
  ->get(function () {
    return new Response([
      'first_name' => 'Jerry',
      'last_name' => 'Cotton',
    ]);
  })

  // Handle PUT request
  ->put(function ($args) {
    $body = $args->request->body;

    // Sanitize input
    $firstName = $this->wire->sanitizer->text($body['first_name'] ?? '');
    $lastName = $this->wire->sanitizer->text($body['last_name'] ?? '');

    // Validate required fields
    if (empty($firstName)) {
      throw new ApiException('First name is required.');
    }

    if (empty($lastName)) {
      throw new ApiException('Last name is required.');
    }

    // Save user details...

    // Respond with updated data
    return (new Response([
      'first_name' => $firstName,
      'last_name' => $lastName,
    ]))->with(['message' => 'User details saved successfully!']);
  });

Endpoint handler arguments

You can access the following properties via the $args parameter of the handler function.

Property	Type	Description
request	Request	Request object
user	\ProcessWire\User	The current ProcessWire user
event	\ProcessWire\HookEvent	ProcessWire URL hook event

$this->addEndpoint('/test-request')->get(function ($args) {
  return new Response([
    'request_path' => $args->request->path,
    'request_method' => $args->request->method,
  ]);
});

Dynamic paths

You can use named arguments to allow dynamic paths. Use $args->request->routeParam() to access named arguments. Endpoint paths support all features provided by ProcessWire URL path hooks, including optional segments and regex constraints.

$this->addEndpoint('/animals/{animal}')->get(function ($args) {
  return new Response([
    'animal_name' => $args->request->routeParam('animal'),
  ]);
});

Querying /animals/bunny-rabbit results in a following JSON:

{
  "data": {
    "animal_name": "bunny-rabbit"
  }
}