Guzzle allows you to serialize HTTP requests and parse HTTP responses using a DSL called a service descriptions. Service descriptions define web service APIs by documenting each operation, the operation's parameters, validation options for each parameter, an operation's response, how the response is parsed, and any errors that can be raised for an operation. Writing a service description for a web service allows you to more quickly consume a web service than writing concrete commands for each web service operation.
Guzzle service descriptions can be representing using a PHP array or JSON document. Guzzle's service descriptions are heavily inspired by Swagger.
A Guzzle Service description must match the following JSON schema document. This document can also serve as a guide when implementing a Guzzle service description.
Download the schema here: Guzzle JSON schema document
{
"additionalProperties": true,
"name": {
"type": "string",
"description": "Name of the web service"
},
"apiVersion": {
"type": ["string", "number"],
"description": "Version identifier that the service description is compatible with"
},
"baseUrl": {
"type": "string",
"description": "Base URL of the web service. Any relative URI specified in an operation will be merged with the baseUrl using the process defined in RFC 2396"
},
"basePath": {
"type": "string",
"description": "Alias of baseUrl"
},
"_description": {
"type": "string",
"description": "Short summary of the web service. This is actually called 'description' but this JSON schema wont validate using just description."
},
"operations": {
"description": "Operations of the web service",
"type": "object",
"properties": {
"extends": {
"type": "string",
"description": "Extend from another operation by name. The parent operation must be defined before the child."
},
"httpMethod": {
"type": "string",
"description": "HTTP method used with the operation (e.g. GET, POST, PUT, DELETE, PATCH, etc)"
},
"uri": {
"type": "string",
"description": "URI of the operation. The uri attribute can contain URI templates. The variables of the URI template are parameters of the operation with a location value of uri"
},
"summary": {
"type": "string",
"description": "Short summary of what the operation does"
},
"class": {
"type": "string",
"description": "Custom class to instantiate instead of the default Guzzle\\Service\\Command\\OperationCommand"
},
"responseClass": {
"type": "string",
"description": "This is what is returned from the method. Can be a primitive, class name, or model name."
},
"responseNotes": {
"type": "string",
"description": "A description of the response returned by the operation"
},
"responseType": {
"type": "string",
"description": "The type of response that the operation creates. If not specified, this value will be automatically inferred based on whether or not there is a model matching the name, if a matching class name is found, or set to 'primitive' by default.",
"enum": [ "primitive", "class", "model", "documentation" ]
},
"deprecated": {
"type": "boolean",
"description": "Whether or not the operation is deprecated"
},
"errorResponses": {
"description": "Errors that could occur while executing the operation",
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "HTTP response status code of the error"
},
"reason": {
"type": "string",
"description": "Response reason phrase or description of the error"
},
"class": {
"type": "string",
"description": "A custom exception class that would be thrown if the error is encountered"
}
}
}
},
"data": {
"type": "object",
"additionalProperties": "true"
},
"parameters": {
"$ref": "parameters",
"description": "Parameters of the operation. Parameters are used to define how input data is serialized into a HTTP request."
},
"additionalParameters": {
"$ref": "parameters",
"description": "Validation and serialization rules for any parameter supplied to the operation that was not explicitly defined."
}
}
},
"models": {
"description": "Schema models that can be referenced throughout the service description. Models can be used to define how an HTTP response is parsed into a Guzzle\\Service\\Resource\\Model object.",
"type": "object",
"properties": {
"$ref": "parameters",
"description": "Parameters of the model. When a model is referenced in a responseClass attribute of an operation, parameters define how a HTTP response message is parsed into a Guzzle\\Service\\Resource\\Model."
}
},
"includes": {
"description": "Service description files to include and extend from (can be a .json, .js, or .php file)",
"type": "array",
"items": {
"type": "string",
"pattern": ".+\\.(js|json|php)$"
}
},
"definitions": {
"parameters": {
"extends": "http://json-schema.org/schema",
"id": "parameters",
"name": {
"type": "string",
"description": "Unique name of the parameter"
},
"type": {
"type": ["string", "array"],
"description": "Type of variable (string, number, integer, boolean, object, array, numeric, null, any). Types are using for validation and determining the structure of a parameter. You can use a union type by providing an array of simple types. If one of the union types matches the provided value, then the value is valid."
},
"instanceOf": {
"type": "string",
"description": "When the type is an object, you can specify the class that the object must implement"
},
"required": {
"type": "boolean",
"description": "Whether or not the parameter is required"
},
"default": {
"description": "Default value to use if no value is supplied"
},
"static": {
"type": "bool",
"description": "Set to true to specify that the parameter value cannot be changed from the default setting"
},
"description": {
"type": "string",
"description": "Documentation of the parameter"
},
"location": {
"type": "string",
"description": "The location of a request used to apply a parameter. Custom locations can be registered with a command, but the defaults are uri, query, statusCode, reasonPhrase, header, body, json, xml, postField, postFile, responseBody"
},
"sentAs": {
"type": "string",
"description": "Specifies how the data being modeled is sent over the wire. For example, you may wish to include certain headers in a response model that have a normalized casing of FooBar, but the actual header is x-foo-bar. In this case, sentAs would be set to x-foo-bar."
},
"filters": {
"type": "array",
"description": "Array of static method names to to run a parameter value through. Each value in the array must be a string containing the full class path to a static method or an array of complex filter information. You can specify static methods of classes using the full namespace class name followed by ‘::’ (e.g. FooBar::baz()). Some filters require arguments in order to properly filter a value. For complex filters, use a hash containing a ‘method’ key pointing to a static method, and an ‘args’ key containing an array of positional arguments to pass to the method. Arguments can contain keywords that are replaced when filtering a value: '@value‘ is replaced with the value being validated, '@api‘ is replaced with the Parameter object.",
"items": {
"type": ["string", {
"object": {
"properties": {
"method": {
"type": "string",
"description": "PHP function to call",
"required": true
},
"args": {
"type": "array"
}
}
}
}]
}
}
}
}
}
Service descriptions are comprised of the following top-level attributes:
{
"name": "string",
"apiVersion": "string|number",
"baseUrl": "string",
"description": "string",
"operations": {},
"models": {},
"includes": ["string.php", "string.json"]
}
| Property Name | Value | Description |
|---|---|---|
| name | string | Name of the web service |
| apiVersion | string|number | Version identifier that the service description is compatible with |
| baseUrl or basePath | string | Base URL of the web service. Any relative URI specified in an operation will be merged with the baseUrl using the process defined in RFC 2396. Some clients require custom logic to determine the baseUrl. In those cases, it is best to not include a baseUrl in the service description, but rather allow the factory method of the client to configure the client’s baseUrl. |
| description | string | Short summary of the web service |
| operations | object containing Operations | Operations of the service. The key is the name of the operation and value is the attributes of the operation. |
| models | object containing Model Schema | Schema models that can be referenced throughout the service description. Models can be used to define how an HTTP response is parsed into a Guzzle\Service\Resource\Model object when an operation uses a model responseType |
| includes | array of .js, .json, or .php files. | Service description files to include and extend from (can be a .json, .js, or .php file) |
| (any additional properties) | mixed | Any additional properties specified as top-level attributes are allowed and will be treated as arbitrary data |
Operations are the actions that can be taken on a service. Each operation is given a unique name and has a distinct endpoint and HTTP method. If an API has a DELETE /users/:id operation, a satisfactory operation name might be DeleteUser with a parameter of id that is inserted into the URI.
{
"operations": {
"operationName": {
"extends": "string",
"httpMethod": "GET|POST|PUT|DELETE|PATCH|string",
"uri": "string",
"summary": "string",
"class": "string",
"responseClass": "string",
"responseNotes": "string",
"type": "string",
"description": "string",
"responseType": "primitive|class|(model by name)|documentation|(string)",
"deprecated": false,
"errorResponses": [
{
"code": 500,
"reason": "Unexpected Error",
"class": "string"
}
],
"data": {
"foo": "bar",
"baz": "bam"
},
"parameters": {}
}
}
}
| Property Name | Value | Description |
|---|---|---|
| extends | string | Extend from another operation by name. The parent operation must be defined before the child. |
| httpMethod | string | HTTP method used with the operation (e.g. GET, POST, PUT, DELETE, PATCH, etc) |
| uri | string | URI of the operation. The uri attribute can contain URI templates. The variables of the URI template are parameters of the operation with a location value of uri |
| summary | string | Short summary of what the operation does |
| class | string | Custom class to instantiate instead of the default Guzzle\Service\Command\OperationCommand. Using this attribute allows you to define an operation using a service description, but allows more customized logic to be implemented in user-land code. |
| responseClass | string | Defined what is returned from the method. Can be a primitive, class name, or model name. You can specify the name of a class to return a more customized result from the operation (for example, a domain model object). When using the name of a PHP class, the class must implement Guzzle\Service\Command\ResponseClassInterface. |
| responseNotes | string | A description of the response returned by the operation |
| responseType | string | The type of response that the operation creates: one of primitive, class, model, or documentation. If not specified, this value will be automatically inferred based on whether or not there is a model matching the name, if a matching class name is found, or set to 'primitive' by default. |
| deprecated | boolean | Whether or not the operation is deprecated |
| errorResponses | array | Errors that could occur while executing the operation. Each item of the array is an object that can contain a 'code' (HTTP response status code of the error), 'reason' (reason phrase or description of the error), and 'class' (an exception class that will be raised when this error is encountered) |
| data | object | Any arbitrary data to associate with the operation |
| parameters | object containing Parameter schema objects | Parameters of the operation. Parameters are used to define how input data is serialized into a HTTP request. |
| additionalParameters | A single Parameter schema object | Validation and serialization rules for any parameter supplied to the operation that was not explicitly defined. |
When a webservice offers a large number of parameters that all are set in the same location (for example the query string or a JSON document), defining each parameter individually can require a lot of time and repetition. Furthermore, some web services allow for completely arbitrary parameters to be supplied for an operation. The additionalParameters attribute can be used to solve both of these issues.
As an example, we can define a Twitter API operation quite easily using additionalParameters. The GetMentions operation accepts a large number of query string parameters. Defining each of these parameters is ideal because it provide much more introspection for the client and opens the possibility to use the description with other tools (e.g. a documentation generator). However, you can very quickly provide a "catch-all" serialization rule that will place any custom parameters supplied to an operation the generated request's query string parameters.
{
"name": "Twitter",
"apiVersion": "1.1",
"baseUrl": "https://api.twitter.com/1.1",
"operations": {
"GetMentions": {
"httpMethod": "GET",
"uri": "statuses/mentions_timeline.json",
"responseClass": "GetMentionsOutput",
"additionalParameters": {
"location": "query"
}
}
},
"models": {
"GetMentionsOutput": {
"type": "object",
"additionalProperties": {
"location": "json"
}
}
}
}
The responseClass attribute is used to define the return value of an operation (what is returned by calling the getResult() method of a command object). The value set in the responseClass attribute can be one of "primitive" (meaning the result with be primitive type like a string), a class name meaning the result will be an instance of a specific user-land class, or a model name meaning the result will be a Guzzle\Service\Resource\Model object that uses a model schema to define how the HTTP response is parsed.
Note
Using a class name with a responseClass will only work if it is supported by the class that is instantiated for the operation. Keep this in mind when specifying a custom class attribute that points to a custom Guzzle\Service\Command\CommandInterface class. The default class, Guzzle\Service\Command\OperationCommand, does support setting custom class attributes.
You can specify the name of a class to return a more customized result from the operation (for example, a domain model object). When using the name of a PHP class, the class must implement Guzzle\Service\Command\ResponseClassInterface. Here's a very simple example of implementing a custom responseClass object.
{
"operations": {
"test": {
"responseClass": "MyApplication\\User"
}
}
}
namespace MyApplication;
use Guzzle\Service\Command\ResponseClassInterface;
use Guzzle\Service\Command\OperationCommand;
class User implements ResponseClassInterface
{
protected $name;
public static function fromCommand(OperationCommand $command)
{
$response = $command->getResponse();
$xml = $response->xml();
return new self((string) $xml->name);
}
public function __construct($name)
{
$this->name = $name;
}
}
errorResponses is an array containing objects that define the errors that could occur while executing the operation. Each item of the array is an object that can contain a 'code' (HTTP response status code of the error), 'reason' (reason phrase or description of the error), and 'class' (an exception class that will be raised when this error is encountered).
Error responses are by default only used for documentation. If you don't need very complex exception logic for your web service errors, then you can use the Guzzle\Plugin\ErrorResponse\ErrorResponsePlugin to automatically throw defined exceptions when one of the errorResponse rules are matched. The error response plugin will listen for the request.complete event of a request created by a command object. Every response (including a successful response) is checked against the list of error responses for an exact match using the following order of checks:
The class attribute must point to a class that implements Guzzle\Plugin\ErrorResponse\ErrorResponseExceptionInterface. This interface requires that an error response class implements public static function fromCommand(CommandInterface $command, Response $response). This method must return an object that extends from \Exception. After an exception is returned, it is thrown by the plugin.
Parameters in both operations and models are represented using the JSON schema syntax.
| Property Name | Value | Description |
|---|---|---|
| name | string | Unique name of the parameter |
| type | string|array | Type of variable (string, number, integer, boolean, object, array, numeric, null, any). Types are using for validation and determining the structure of a parameter. You can use a union type by providing an array of simple types. If one of the union types matches the provided value, then the value is valid. |
| instanceOf | string | When the type is an object, you can specify the class that the object must implement |
| required | boolean | Whether or not the parameter is required |
| default | mixed | Default value to use if no value is supplied |
| static | boolean | Set to true to specify that the parameter value cannot be changed from the default setting |
| description | string | Documentation of the parameter |
| location | string | The location of a request used to apply a parameter. Custom locations can be registered with a command, but the defaults are uri, query, statusCode, reasonPhrase, header, body, json, xml, postField, postFile, responseBody |
| sentAs | string | Specifies how the data being modeled is sent over the wire. For example, you may wish to include certain headers in a response model that have a normalized casing of FooBar, but the actual header is x-foo-bar. In this case, sentAs would be set to x-foo-bar. |
| filters | array | Array of functions to to run a parameter value through. |
Each value in the array must be a string containing the full class path to a static method or an array of complex filter information. You can specify static methods of classes using the full namespace class name followed by "::" (e.g. FooBar::baz()). Some filters require arguments in order to properly filter a value. For complex filters, use an object containing a method attribute pointing to a function, and an args attribute containing an array of positional arguments to pass to the function. Arguments can contain keywords that are replaced when filtering a value: @value is replaced with the value being filtered, and @api is replaced with the actual Parameter object.
{
"filters": [
"strtolower",
{
"method": "MyClass::convertString",
"args": [ "test", "@value", "@api" ]
}
]
}
The above example will filter a parameter using strtolower. It will then call the convertString static method of MyClass, passing in "test", the actual value of the parameter, and a Guzzle\Service\Description\Parameter object.
The location field of top-level parameters control how a parameter is serialized when generating a request.
Parameters are injected into the uri attribute of the operation using URI-template expansion.
{
"operations": {
"uriTest": {
"uri": "/test/{testValue}",
"parameters": {
"testValue": {
"location": "uri"
}
}
}
}
}
Parameters are injected into the query string of a request. Query values can be nested, which would result in a PHP style nested query string. The name of a parameter is the default name of the query string parameter added to the request. You can override this behavior by specifying the sentAs attribute on the parameter.
{
"operations": {
"queryTest": {
"parameters": {
"testValue": {
"location": "query",
"sentAs": "test_value"
}
}
}
}
}
Parameters are injected as headers on an HTTP request. The name of the parameter is used as the name of the header by default. You can change the name of the header created by the parameter using the sentAs attribute.
Headers that are of type object will be added as multiple headers to a request using the key of the input array as the header key. Setting a sentAs attribute along with a type object will use the value of sentAs as a prefix for each header key.
Parameters are injected as the body of a request. The input of these parameters may be anything that can be cast to a string or a Guzzle\Http\EntityBodyInterface object.
Parameters are inserted as POST fields in a request. Nested values may be supplied and will be represented using PHP style nested query strings. The POST field name is the same as the parameter name by default. You can use the sentAs parameter to override the POST field name.
Parameters are added as POST files. A postFile value may be a string pointing to a local filename or a Guzzle\Http\Message\PostFileInterface object. The name of the POST file will be the name of the parameter by default. You can use a custom POST file name by using the sentAs attribute.
Supports "string" and "array" types.
Parameters are added to the body of a request as top level keys of a JSON document. Nested values may be specified, with any number of nested Guzzle\Common\ToArrayInterface objects. When JSON parameters are specified, the Content-Type of the request will change to application/json if a Content-Type has not already been specified on the request.
Parameters are added to the body of a request as top level nodes of an XML document. Nested values may be specified, with any number of nested Guzzle\Common\ToArrayInterface objects. When XML parameters are specified, the Content-Type of the request will change to application/xml if a Content-Type has not already been specified on the request.
Specifies the EntityBody of a response. This can be used to download the response body to a file or a custom Guzzle EntityBody object.
If a parameter has no location attribute, then the parameter is simply used as a data value.
Custom locations can be registered as new locations or override default locations if needed.
Models are used in service descriptions to provide generic JSON schema definitions that can be extended from or used in $ref attributes. Models can also be referenced in a responseClass attribute to provide valuable output to an operation. Models are JSON schema documents and use the exact syntax and attributes used in parameters.
Response models describe how a response is parsed into a Guzzle\Service\Resource\Model object. Response models are always modeled as JSON schema objects. When an HTTP response is parsed using a response model, the rules specified on each property of a response model will translate 1:1 as keys in a PHP associative array. When a sentAs attribute is found in response model parameters, the value retrieved from the HTTP response is retrieved using the sentAs parameter but stored in the response model using the name of the parameter.
The location field of top-level parameters in a response model tell response parsers how data is retrieved from a response.
Retrieves the status code of the response.
Retrieves the reason phrase of the response.
Retrieves a header from the HTTP response.
Retrieves the body of an HTTP response.
Retrieves a top-level parameter from a JSON document contained in an HTTP response.
You can use additionalProperties if the JSON document is wrapped in an outer array. This allows you to parse the contents of each item in the array using the parsing rules defined in the additionalProperties schema.
Retrieves a top-level node value from an XML document contained in an HTTP response.
Custom locations can be registered as new locations or override default locations if needed.
Let's say you're interacting with a web service called 'Foo' that allows for the following routes and methods:
GET/POST /users
GET/DELETE /users/:id
The following JSON service description implements this simple web service:
{
"name": "Foo",
"apiVersion": "2012-10-14",
"baseUrl": "http://api.foo.com",
"description": "Foo is an API that allows you to Baz Bar",
"operations": {
"GetUsers": {
"httpMethod": "GET",
"uri": "/users",
"summary": "Gets a list of users",
"responseClass": "GetUsersOutput"
},
"CreateUser": {
"httpMethod": "POST",
"uri": "/users",
"summary": "Creates a new user",
"responseClass": "CreateUserOutput",
"parameters": {
"name": {
"location": "json",
"type": "string"
},
"age": {
"location": "json",
"type": "integer"
}
}
},
"GetUser": {
"httpMethod": "GET",
"uri": "/users/{id}",
"summary": "Retrieves a single user",
"responseClass": "GetUserOutput",
"parameters": {
"id": {
"location": "uri",
"description": "User to retrieve by ID",
"required": true
}
}
},
"DeleteUser": {
"httpMethod": "DELETE",
"uri": "/users/{id}",
"summary": "Deletes a user",
"responseClass": "DeleteUserOutput",
"parameters": {
"id": {
"location": "uri",
"description": "User to delete by ID",
"required": true
}
}
}
},
"models": {
"GetUsersOutput": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"location": "json",
"type": "string"
},
"age": {
"location": "json",
"type": "integer"
}
}
}
},
"CreateUserOutput": {
"type": "object",
"properties": {
"id": {
"location": "json",
"type": "string"
},
"location": {
"location": "header",
"sentAs": "Location",
"type": "string"
}
}
},
"GetUserOutput": {
"type": "object",
"properties": {
"name": {
"location": "json",
"type": "string"
},
"age": {
"location": "json",
"type": "integer"
}
}
},
"DeleteUserOutput": {
"type": "object",
"properties": {
"status": {
"location": "statusCode",
"type": "integer"
}
}
}
}
}
If you attach this service description to a client, you would completely configure the client to interact with the Foo web service and provide valuable response models for each operation.
use Guzzle\Service\Description\ServiceDescription;
$description = ServiceDescription::factory('/path/to/client.json');
$client->setDescription($description);
$command = $client->getCommand('DeleteUser', array('id' => 123));
$responseModel = $client->execute($command);
echo $responseModel['status'];
Note
You can add the service description to your client's factory method or constructor.