This tutorial has a new version, check it out!
> APIs > Symfony RESTful API: Errors (Course 2)
Login to bookmark this video
Buy Access to Course
13.

The Helpful Detail Key

Share this awesome video!

|

Keep on Learning!

Start your All-Access Pass

With a Subscription, click any sentence in the script to jump to that part of the video!

Login Subscribe

Our end goal is to make our API easy to use so if something goes wrong our clients can actually debug it without pulling their hair out or having to email us.

Whenever you throw an exception in PHP there is going to be a message, like "No programmer found for username":

187 lines | src/AppBundle/Controller/Api/ProgrammerController.php
// ... lines 1 - 18
class ProgrammerController extends BaseController
{
// ... lines 21 - 54
public function showAction($nickname)
{
$programmer = $this->getDoctrine()
->getRepository('AppBundle:Programmer')
->findOneByNickname($nickname);
if (!$programmer) {
throw $this->createNotFoundException(sprintf(
'No programmer found with nickname "%s"',
$nickname
));
}
// ... lines 67 - 70
}
// ... lines 72 - 185
}

This message is usually just for us as developers. When we're in development mode we see this message, but our clients don't. But, sometimes this message is useful, like in this case. Having something in the response that says "No programmer found for username" would help me as a client know that I have the right URL but that nickname I'm trying to use is missing.

There are other cases where we don't want to show the exception message. For example, if our database credentials are incorrect and we're getting a 500 error, we don't want to tell our client "invalid database credentials" -- that is a detail to hide.

Introducing the detail Property

Back in the spec, do we have a field for this? It's not supposed to be title, because that's supposed to be the same for every type. We could always add our own but if you look there is something called "detail" which is a "human readable explanation specific to this occurence of the problem." That's perfect for our use case!

Back in ProgrammerControllerTest let's look for this exact message, "No programmer found for username".

At the bottom we'll say $this->asserter()->assertResponsePropertyEquals() we'll fill this in so that when there's a 404 there will be a detail field and it should be set to "No programmer found for username fake" because that's what's in the URL:

177 lines | src/AppBundle/Tests/Controller/Api/ProgrammerControllerTest.php
// ... lines 1 - 5
class ProgrammerControllerTest extends ApiTestCase
{
// ... lines 8 - 165
public function test404Exception()
{
$response = $this->client->get('/api/programmers/fake');
// ... lines 169 - 173
$this->asserter()->assertResponsePropertyEquals($response, 'detail', 'No programmer found with nickname "fake"');
}
}

And if we try this out in our terminal, it's failing nice:

./bin/phpunit -c app --filter test404Exception

There's no detail property yet. But no worries, creating that is easy! It all happens inside of our ApiExceptionSubscriber.

Adding Exception Message as detail

Very simply, we say $apiProblem->set() since that allows us to put in new fields. And we'll pass that detail and $e->getMessage():

55 lines | src/AppBundle/EventListener/ApiExceptionSubscriber.php
// ... lines 1 - 12
class ApiExceptionSubscriber implements EventSubscriberInterface
{
public function onKernelException(GetResponseForExceptionEvent $event)
{
// ... lines 17 - 34
$apiProblem->set('detail', $e->getMessage());
// ... lines 36 - 45
}
// ... lines 47 - 53
}

And that should do it, but don't do that...because that will expose the exception message of every exception in our system which is definitely not what we want to do.

So there has to be some way for us to determine whether or not it is safe to show the message to the user. There are a number of different ways to do this, FOSRestBundle has some options where you can whitelist on a class by class basis. And that's something we could even do here with an if statement that looks for a set of classes that are safe.

Implementing your own interface is also an option! I'll do something simple here which may or may not work for you, so do think about your project critically when you choose how to do this.

I'll check to see if ($e instanceof HttpExceptionInterface):

55 lines | src/AppBundle/EventListener/ApiExceptionSubscriber.php
// ... lines 1 - 14
public function onKernelException(GetResponseForExceptionEvent $event)
{
// ... lines 17 - 33
if ($e instanceof HttpExceptionInterface) {
$apiProblem->set('detail', $e->getMessage());
}
// ... lines 37 - 45
}
// ... lines 47 - 55

This is used for 404 or 403 errors, so it's typically things that we are in control of.

And you can see here that our 404 error implements that interface which will allow it to be caught by that.

Head back to the terminal and test that guy out:

./bin/phpunit -c app --filter test404Exception

Beautiful!

Now we have the opportunity to be more helpful to our users whenever we have a 404 error. Or, if you're creating an ApiProblem by hand, you can set the detail field manually.