README

This library provides a simple and straightforward implementation of the IETF Problem Details for HTTP APIs, RFC 9457.

RFC 9457 is a simple specification for formatting error responses from RESTful APIs on the web. This library provides a simple and convenient way to interact with that specification. It supports generating and parsing RFC 9457 messages, in both JSON and XML variants.

Generating responses

What's that you say? Someone sent your API a bad request? Tell them it's a problem!

use Crell\ApiProblem\ApiProblem;

$problem = new ApiProblem("You do not have enough credit.", "http://example.com/probs/out-of-credit");
// Defined properties in the API have their own setter methods.
$problem
  ->setDetail("Your current balance is 30, but that costs 50.")
  ->setInstance("http://example.net/account/12345/msgs/abc");
// But you can also support any arbitrary extended properties!
$problem['balance'] = 30;
$problem['accounts'] = [
  "http://example.net/account/12345",
  "http://example.net/account/67890"
];

$json_string = $problem->asJson();

// Now send that JSON string as a response along with the appropriate HTTP error
// code and content type which is available via ApiProblem::CONTENT_TYPE_JSON.
// Also check out asXml() and ApiProblem::CONTENT_TYPE_XML for the angle-bracket fans in the room.

Or, even better, you can subclass ApiProblem for a specific problem type (since the type and title are supposed to go together and be relatively fixed), then just populate your own error-specific data. Just like extending an exception!

If you're using a library or framework that wants to do its own JSON serialization, that's also fully supported. ApiProblem implements\JsonSerializable, so you can pass it directly to json_encode() as if it were a naked array.

$response = new MyFrameworksJsonResponse($problem);

// Or do it yourself
$body = json_encode($problem);

Sending Responses

You're probably using PSR-7 for your responses. That's why this library includes a utility to convert your ApiProblem object to a PSR-7 ResponseInterface object, using a PSR-17 factory of your choice. Like so:

use Crell\ApiProblem\HttpConverter;

$factory = getResponseFactoryFromSomewhere();

// The second parameter says whether to pretty-print the output.
$converter = new HttpConverter($factory, true);

$response = $converter->toJsonResponse($problem);
// or
$response = $converter->toXmlResponse($problem);

That gives back a fully-functional and marked Response object, ready to send back to the client.

Receiving responses

Are you sending messages to an API that is responding with API-Problem errors? No problem! You can easily handle that response like so:

use Crell\ApiProblem\ApiProblem;

$problem = ApiProblem::fromJson($some_json_string);
$title = $problem->getTitle();
$type = $problem->getType();
// Great, now we know what went wrong, so we can figure out what to do about it.

(It works for fromXml(), too!)

Installation

Install ApiProblem like any other Composer package:

composer require crell/api-problem

See the Composer documentation for more details.

Security

If you discover any security related issues, please use the GitHub security reporting form rather than the issue queue.

Credits

[Larry Garfield][link-author]
[All Contributors][link-contributors]

License

This library is released under the MIT license. In short, "leave the copyright statement intact, otherwise have fun." See LICENSE for more information.

Contributing

Pull requests accepted! The goal is complete conformance with the IETF spec.

crell / api-problem

Maintainers

Details