zircote / api-problem
An Api Problem Exception implementation in PHP. See: http://tools.ietf.org/html/draft-nottingham-http-problem for the latest on the specification
dev-master
2013-12-16 13:57 UTC
This package is not auto-updated.
Last update: 2024-11-04 15:00:28 UTC
README
ApiProblem
is an attempt to provide the functionality and problem reporting as defined in
Problem Details for HTTP APIs. The goal being a simple
Exception wrapper for PHP that can send the desired response in JSON
and XML
.
Use
The sendHttpResponse
method
The sendHTTPResponse
has two parameter, both optional $format
and $terminate
.
format
:ApiProblem::FORMAT_XML
:application/api-problem+json
ApiProblem::FORMAT_JSON
:application/api-problem+xml
terminate
:bool
true
(default) headers are sent and execution is terminated.false
the body payload is returned
JSON Example
<?php $apiProblem = new ApiProblem( 'http://api-problem.domain.com/some-url.html', 'Bad Request', 400, 'some detail', 'http://domain.com/this-request' ); $apiProblem->sendHTTPResponse(ApiProblem::FORMAT_JSON);
Result
HTTP/1.0 400 Bad Request Access-Control-Allow-Origin: * Content-Type: application/api-problem+json Link: <http://api-problem.domain.com/some-url.html>; rel="http://api-problem.domain.com/some-url.html" title="Bad Request" { "problemType": "http://api-problem.domain.com/some-url.html", "title": "Bad Request", "httpStatus": 400, "detail": "some detail", "problemInstance": "http://domain.com/this-request" }
XML Example
<?php try { throw new ApiProblem( 'http://api-problem.domain.com/some-url.html', 'Bad Request', 400, 'some detail', 'http://domain.com/this-request' ); } catch (ApiProblem $e) { $e->sendHTTPResponse(ApiProblem::FORMAT_XML); }
Result
HTTP/1.0 400 Bad Request Access-Control-Allow-Origin: * Content-Type: application/api-problem+xml Link: <http://api-problem.domain.com/some-url.html>; rel="http://api-problem.domain.com/some-url.html"; title="Bad Request" <?xml version="1.0" encoding="UTF-8"?> <problem xmlns="urn:ietf:draft:nottingham-http-problem"> <problemType>http://api-problem.domain.com/some-url.html</problemType> <title>Bad Request</title> <httpStatus>400</httpStatus> <detail>some detail</detail> <problemInstance>http://domain.com/this-request</problemInstance> </problem>
Adding additional headers, i.e. CORS, Auth, etc
<?php $apiProblem = new ApiProblem( 'http://api-problem.domain.com/some-url.html', 'Unauthorized', 401, 'some detail', 'http://domain.com/this-request' ); $apiProblem->setHeader('Access-Control-Allow-Origin', '*'); $apiProblem->setHeader('WWW-Authenticate', 'bearer realm="my_realm"'); $apiProblem->sendHTTPResponse(ApiProblem::FORMAT_JSON);
Result
HTTP/1.0 401 Unauthorized Access-Control-Allow-Origin: * WWW-Authenticate: bearer realm="my_realm" Content-Type: application/api-problem+json Link: <http://api-problem.domain.com/some-url.html>; rel="http://api-problem.domain.com/some-url.html" title="Bad Request" { "problemType": "http://api-problem.domain.com/some-url.html", "title": "Unauthorized", "httpStatus": 401, "detail": "some detail", "problemInstance": "http://domain.com/this-request" }
Adding extended data to the problem instance:
<?php $apiProblem = new ApiProblem( 'http://api-problem.domain.com/some-url.html', 'Unauthorized', 401, 'some detail', 'http://domain.com/this-request' ); $apiProblem->setExtensionData('ext_test', 'etx_test_value'); $apiProblem->setExtensionData('ext_test_array_i', array('a' => 'a_d', 'b' => 'b_d', 'c' => 'c_d')); $apiProblem->setExtensionData('ext_test_array_ni', array('a', 'b', 'c')); $apiProblem->sendHTTPResponse(ApiProblem::FORMAT_JSON);
Result
HTTP/1.0 401 Unauthorized Content-Type: application/api-problem+json Link: <http://api-problem.domain.com/some-url.html>; rel="http://api-problem.domain.com/some-url.html" title="Bad Request" { "problemType": "http://api-problem.domain.com/some-url.html", "title": "Unauthorized", "httpStatus": 401, "detail": "some detail", "problemInstance": "http://domain.com/this-request", "ext_test":"etx_test_value", "ext_test_array_i":{ "a":"a_d", "b":"b_d", "c":"c_d" } "ext_test_array_ni":[ "a", "b", "c" ] }