You want to let people read a resource.
Read requests using GET. Return structured results, using formats such as JSON, XML, or HTML. Don’t modify any resources.
For a GET request to the resource at http://api.example.com/v1/jobs/123:
|
1 2 |
GET /v1/jobs/123 HTTP/1.1 Host: api.example.com |
Use this PHP code:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
// Assume this was pulled from a database or other data store $job[123] = [ 'id' => 123, 'position' => [ 'title' => 'PHP Developer', ], ]; $json = json_encode($job[123]); // Resource exists 200: OK http_response_code(200); // And it's being sent back as JSON header('Content-Type: application/json'); print $json; |
To generate this HTTP response:
|
1 2 3 4 5 6 7 8 9 10 |
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 61 { "id": 123, "position": { "title": "PHP Developer" } } |
The most common type of REST request is reading data. Reads in REST correspond with HTTP GET requests.
This is the same HTTP method used by your web browser to read an HTML page, so when you write PHP scripts you’re almost always handling GET requests.
This makes serving up a REST resource for reading straightforward:
1. Check that the HTTP method is GET.
2. Parse the URL to determine the specific resource and, optionally, key.
3. Retrieve the necessary information, probably from a database.
4. Format the data into the proper structure
5. Send the data back, along with the necessary HTTP headers.
The first steps are covered in Recipe 15.1 and the third is specific to your application.
Once you’ve fetched the data, the next step is formatting it for output. It’s common to use JSON or XML (or both), but any structured format is perfectly fine.
That could be HTML or YAML or even CSV.
This example takes a record and converts it to JSON:
|
1 2 3 4 5 6 7 8 9 |
// Assume this was pulled from a database or other data store $job[123] = [ 'id' => 123, 'position' => [ 'title' => 'PHP Developer', ], ]; $json = json_encode($job[123]); |
After you have the response body, the other step is sending the appropriate HTTP headers.
Because this record was found, return a status code of 200 (OK) and because you’re using JSON, set the Content-Type header:
|
1 2 3 4 5 |
// Resource exists 200: OK http_response_code(200); // And it's being sent back as JSON header('Content-Type: text/json'); |
Last, send the data itself:
|
1 |
print $json; |
If there is no Job 123 in the system, tell the caller this wasn’t found using status code 404:
|
1 2 |
// Resource exists 404: Not Found http_response_code(404); |
GET requests also have the requirement of not modifying the system. In other words, reading a resource shouldn’t cause that resource—or any other part of your data—to change. The technical phrase for this is “safe.”
