Basic Routing and Controller¶

To make this endpoint work, go back to ProgrammerController, and add another routing line. But this time, make the URL respond to the GET method:

// src/KnpU/CodeBattle/Controller/Api/ProgrammerController.php
// ...

protected function addRoutes(ControllerCollection $controllers)
{
    $controllers->post('/api/programmers', array($this, 'newAction'));

    $controllers->get('/api/programmers/{nickname}', array($this, 'showAction'));
}

The {nickname} in the URL means that this route will be matched by any GET request that looks like /api/programmers/*. Next, make a showAction method and just return a simple message:

// src/KnpU/CodeBattle/Controller/Api/ProgrammerController.php
// ...

public function showAction($nickname)
{
    return 'Hello '.$nickname;
}

If we go to /api/programmers/foo, the $nickname variable will be equal to foo. This is special to Silex, but you can do this kind of stuff with any framework.

Ok, try out the testing script:

$ php testing.php

HTTP/1.1 200 OK
# ...
Content-Type: text/html; charset=UTF-8

Hello ObjectOrienter366

Returning a JSON Response¶

Our goal is to return a representation of the programmer resource. This could be in JSON, XML and if it’s April Fools try some invented format. We’ll use JSON, because it’s easy simple, and all languages support it. To do this, first query for the programmer by using its nickname. I’ll do this using a findOneByNickname method from my simple ORM:

// src/KnpU/CodeBattle/Controller/Api/ProgrammerController.php
// ...

public function showAction($nickname)
{
    $programmer = $this->getProgrammerRepository()->findOneByNickname($nickname);

    // ...
}

This returns a Programmer object. The code you use to query for data will be different. The really important part is to finish with an object that has all the data you want to send back in your API.

Next, just turn the Programmer object into an array manually. And finally, create a new Response object just like the POST endpoint. But this time, set its body to be the JSON-encoded string:

// src/KnpU/CodeBattle/Controller/Api/ProgrammerController.php
// ...

public function showAction($nickname)
{
    $programmer = $this->getProgrammerRepository()->findOneByNickname($nickname);

    $data = array(
        'nickname' => $programmer->nickname,
        'avatarNumber' => $programmer->avatarNumber,
        'powerLevel' => $programmer->powerLevel,
        'tagLine' => $programmer->tagLine,
    );

    return new Response(json_encode($data), 200);
}

The correct status code is 200. We’ll learn about other status codes, but you’ll still use the good ol’ 200 in most cases, especially for GET requests.

Test it out!

$ php testing.php

HTTP/1.1 200 OK
# ...
Content-Type: text/html; charset=UTF-8

{"nickname":"ObjectOrienter135","avatarNumber":"5","powerLevel":"0","tagLine":"a test dev!"}

But what’s the Content-Type?¶

Perfect! Except that we’re still telling the client that the content is written in HTML. That’s the job of the Content-Type response header, and it defaults to text/html. Our response is being dishonest right now, and we risk confusing an API client.

Fix this by manually setting the Content-Type header on the Response before returning it:

// src/KnpU/CodeBattle/Controller/Api/ProgrammerController.php
// ...

public function showAction($nickname)
{
    // ...

    $response = new Response(json_encode($data), 200);
    $response->headers->set('Content-Type', 'application/json');

    return $response;
}

How you set a response header may be different in your app, but there is definitely a way to do this. And because the Content-Type header is so important, you may even have a shortcut method for it.

Response::json(array('name' => 'Steve', 'state' => 'CA'));

We’re now returning a JSON representation of the resource, setting its Content-Type header correctly and using the right status code. Great work.

404 Pages¶

But let’s not forget to return a 404 if we’re passed a bad nickname. In our app, I’ve created a shortcut for this called throw404:

// src/KnpU/CodeBattle/Controller/Api/ProgrammerController.php
// ...

public function showAction($nickname)
{
    $programmer = $this->getProgrammerRepository()->findOneByNickname($nickname);

    if (!$programmer) {
        $this->throw404('Crap! This programmer has deserted! We\'ll send a search party');
    }

    // ...
}

Under the surface, this throws a special type of exception that’s converted by Silex into a 404 response. In your app, just return a 404 page however you normally do.

Try it out by temporarily changing our testing script to point to a made-up nickname:

// testing.php
// ...

// 2) GET a programmer resource
$request = $client->get('/api/programmers/abcd'.$nickname);
$response = $request->send();

echo $response;
echo "\n\n";

When we run the script now, we do see a 404 page, though it’s a big ugly HTML page instead of JSON. We’ll talk about properly handling API errors later.