Error Responses¶

Responding with an Error¶

The nnrestapi has a few shortcuts built in to respond with error codes, if the request parameters were invalid or the requested data could not be retrieved.

Have a look at the class Nng\Nnrestapi\Mvc\Response to see all available options.

Here we are checking for a model. If it can’t be found, we return a 404 NOT FOUND error:

<?php
namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Test extends AbstractApi
{
   /**
    * Call via GET-request with an uid: https://www.mywebsite.com/api/test/1
    *
    * @Api\Access("public")
    * @return array
    */
   public function getIndexAction( $uid = null )
   {
      $entry = $this->entryRepository->findByUid( $uid );
      if (!$entry) {
         return $this->response->notFound('Model with uid [' . $uid . '] was not found.');
      }
      return $entry;
   }
}

If you open the URL https://www.mywebsite.com/api/test/1 in your browser and pass the uid of an entry that does not exist, you will see the following JSON response. It will be sent with a 404 NOT FOUND header:

{"status":404, "error":"Model with uid [1] was not found."}

Responding by throwing an Error¶

An alternative way to respond with an Error is by throwing an Nng\Nnrestapi\Error\ApiError. This allows adding a custom error code, e.g. for better evaluating and displaying / localizing the error in your frontend application.

To immediatly throw the ApiError and abort further processing, you can use the \nn\rest::Error()-Helper:

// basic syntax
\nn\rest::Error( $message, $httpErrorCode, $myCustomErrorCode );

// examples
\nn\rest::Error( 'Nothing here, bro.', 404, 'ERROR.NOTHING' );
\nn\rest::Error( 'Not your district, bro.', 403, 1234567 );

The last example above will send a 403 Unauthorized header and a JSON with the message and custom error code:

{"status":403, "error":"Not your district, bro.", "code":123567}

Full example

<?php
namespace My\Extension\Api;

use Nng\Nnrestapi\Annotations as Api;
use Nng\Nnrestapi\Api\AbstractApi;

/**
 * @Api\Endpoint()
 */
class Test extends AbstractApi
{
   /**
    * Call via GET-request with an uid: https://www.mywebsite.com/api/test
    *
    * @Api\Access("public")
    * @return array
    */
   public function getIndexAction()
   {
      if ($this->someCheckFailed()) {
         \nn\rest::Error( 'the check failed', 403, 612523 );
      }

      return ['everything'=>'fine'];
   }
}

Overview of error codes¶

shortcut	code	description
`$this->response->success([...], 'OK')`	200	OK - sent, if no other option was called
`$this->response->noContent('message')`	204	Empty response
`$this->response->unauthorized('message')`	403	Unauthorized (not logged in)
`$this->response->forbidden('message')`	403	Alias to unauthorized
`$this->response->notFound('message')`	404	Not found
`$this->response->invalid('message')`	422	Invalid request parameters
`$this->response->error($code, 'message')`	any	Custom response