Returning application/problem+json for Security Errors¶

Next, we need all of our errors to always return that same API problem response format. And when we return this format, we should always send back its special Content-Type so let’s make sure it’s correct:

# features/api/authentication.feature
# ...

Scenario: Create a programmer without authentication
  # ...
  And the "Content-Type" header should be "application/problem+json"

Ahh! It’s not coming back with that. We are getting an application/problem-like format, but without the right Content-Type header. It’s coming back as a simple application/json.

In our app, when an exception is thrown, there are 2 different places that take care of things. Most errors are handled in the Application class. We added this in episode 1. But security errors are handled in ApiEntryPoint, and it’s responsible for returning some helpful response:

// src/KnpU/CodeBattle/Security/Authentication/ApiEntryPoint.php
// ...

public function start(Request $request, AuthenticationException $authException = null)
{
    $message = $this->getMessage($authException);

    $response = new JsonResponse(array('detail' => $message), 401);

    return $response;
}

So for example here, you can see why we get the detail and why we get the 401. If I change this to 403, this proves that this class is responsible for the error responses. Let’s add the application/problem+json Content-Type header:

// src/KnpU/CodeBattle/Security/Authentication/ApiEntryPoint.php
// ...

public function start(Request $request, AuthenticationException $authException = null)
{
    $message = $this->getMessage($authException);

    $response = new JsonResponse(array('detail' => $message), 401);
    $response->headers->set('Content-Type', 'application/problem+json');

    return $response;
}

Using the ApiProblem Class For Security Errors¶

For consistency, one of the things we did in Episode 1 is actually create an ApiProblem class. The idea was whenever you had some sort of error response you needed to send back, you could create this ApiProblem object, which will help you structure things and avoid typos in any keys.

Right now inside of the ApiEntryPoint, we’re kind of creating the API problem structure by hand, which is something I don’t want to do. Let’s leverage our ApiProblem class instead.

So first, I’m closing a couple of these classes. Inside ApiProblem there is a type property. The spec document that describes this format says that we should have a type field and that it should be a unique string for each error in your application. Right now we have two: validation_error as one unique thing that can go wrong and invalid_body_format as another:

// src/KnpU/CodeBattle/Api/ApiProblem.php
// ...

class ApiProblem
{
    const TYPE_VALIDATION_ERROR = 'validation_error';
    const TYPE_INVALID_REQUEST_BODY_FORMAT = 'invalid_body_format';

    // ...
}

That’s if the client sends us json, but the json is malformed. Now we have a third type of error, which is when you send us bad credentials. So let’s add a new constant here called authentication_error. And I’m just making up this string, it’s not terribly important. And then down here is a map from those types to a human readable text that will live on the title key:

// src/KnpU/CodeBattle/Api/ApiProblem.php
// ...

class ApiProblem
{
    // ...
    const TYPE_AUTHENTICATION_ERROR = 'authentication_error';

    private static $titles = array(
        // ...
        self::TYPE_AUTHENTICATION_ERROR => 'Invalid or missing authentication',
    );
}

The purpose of this is that when we create a new ApiProblem, we are forced to pass in a type and then that has a nice little map to the title. So given a certain type, you always get this nice same identical human readable explanation for it. You don’t have to duplicate the titles all around your codebase.

Back in ApiEntryPoint, instead of this stuff, you can create a new ApiProblem object. Add our use statement for that. The status code we know is 401 and the type is going to be our new authentication_error type:

// src/KnpU/CodeBattle/Security/Authentication/ApiEntryPoint.php
// ...

public function start(Request $request, AuthenticationException $authException = null)
{
    $message = $this->getMessage($authException);

    $problem = new ApiProblem(401, ApiProblem::TYPE_AUTHENTICATION_ERROR);
    $problem->set('detail', $message);

    $response = new JsonResponse($problem->toArray(), 401);
    $response->headers->set('Content-Type', 'application/problem+json');

    return $response;
}

So it’s a nice way to make sure we don’t just invent new types all over the place.

And then, we set the detail. The detail is going to be the message that comes from Silex whenever something goes wrong related to security. Based on what went wrong, we will get a different message here and we can use the translator to control it.

Then down here for the response, we can say just new JsonResponse. For the content, we can say $problem->toArray(). This is a function we used earlier: it just takes all those properties and turns them into an array. Now we’ll use $problem->getStatusCode(). And we’ll keep the response headers already set.

So this is a small improvement. I’m more consistent in my code, so my API will be more consistent too. If I need to create an api problem response, I won’t do it by hand. The ApiProblem class does some special things for us, attaching the title and making sure we have a few defined types. If we try this, we should get the same result as before and we do. Perfect.