path: root/vendor/guzzle/guzzle/docs/webservice-client/guzzle-service-descriptions.rst

===========================
Guzzle service descriptions
===========================

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 <http://swagger.wordnik.com/>`_.

Service description schema
==========================

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: :download:`Guzzle JSON schema document </_downloads/guzzle-schema-1.0.json>`

.. class:: overflow-height-500px

    .. literalinclude:: ../_downloads/guzzle-schema-1.0.json
        :language: json

Top-level attributes
--------------------

Service descriptions are comprised of the following top-level attributes:

.. code-block:: json

    {
        "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 of the service. The key is the name of the operation and value is the attributes of the operation.         |
|                                         | :ref:`operation-schema` |                                                                                                                       |
|                                         |                         |                                                                                                                       |
+-----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------------------------------+
| models                                  | object containing       | Schema models that can be referenced throughout the service description. Models can be used to define how an HTTP     |
|                                         | :ref:`model-schema`     | response is parsed into a ``Guzzle\Service\Resource\Model`` object when an operation uses a ``model`` ``responseType``|
+-----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------------------------------+
| includes                                | array of .js,           | Service description files to include and extend from (can be a .json, .js, or .php file)                              |
|                                         | .json, or .php          |                                                                                                                       |
|                                         | files.                  |                                                                                                                       |
+-----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------------------------------+
| (any additional properties)             | mixed                   | Any additional properties specified as top-level attributes are allowed and will be treated as arbitrary data         |
+-----------------------------------------+-------------------------+-----------------------------------------------------------------------------------------------------------------------+

.. _operation-schema:

Operations
----------

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.

.. class:: overflow-height-250px

    .. code-block:: json

        {
            "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": {}
                }
            }
        }

.. csv-table::
   :header: "Property Name", "Value", "Description"
   :widths: 20, 15, 65

    "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 :ref:`parameter-schema` objects", "Parameters of the operation. Parameters are used to define how input data is serialized into a HTTP request."
    "additionalParameters", "A single :ref:`parameter-schema` object", "Validation and serialization rules for any parameter supplied to the operation that was not explicitly defined."

additionalParameters
~~~~~~~~~~~~~~~~~~~~

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.

.. class:: overflow-height-250px

    .. code-block:: json

        {
            "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"
                    }
                }
            }
        }

responseClass
~~~~~~~~~~~~~

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 :ref:`model schema <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.

.. code-block:: json

    {
        "operations": {
            "test": {
                "responseClass": "MyApplication\\User"
            }
        }
    }

.. code-block:: php

    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
~~~~~~~~~~~~~~

``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).

ErrorResponsePlugin
^^^^^^^^^^^^^^^^^^^

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:

1. Does the errorResponse have a defined ``class``?
2. Is the errorResponse ``code`` equal to the status code of the response?
3. Is the errorResponse ``reason`` equal to the reason phrase of the response?
4. Throw the exception stored in the ``class`` attribute of the errorResponse.

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.

.. _parameter-schema:

Parameter schema
----------------

Parameters in both operations and models are represented using the
`JSON schema <http://tools.ietf.org/id/draft-zyp-json-schema-04.html>`_ syntax.

.. csv-table::
   :header: "Property Name", "Value", "Description"
   :widths: 20, 15, 65

    "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."

filters
~~~~~~~

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.

.. code-block:: json

    {
        "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.

Operation parameter location attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The location field of top-level parameters control how a parameter is serialized when generating a request.

uri location
^^^^^^^^^^^^

Parameters are injected into the ``uri`` attribute of the operation using
`URI-template expansion <http://tools.ietf.org/html/rfc6570>`_.

.. code-block:: json

    {
        "operations": {
            "uriTest": {
                "uri": "/test/{testValue}",
                "parameters": {
                    "testValue": {
                        "location": "uri"
                    }
                }
            }
        }
    }

query location
^^^^^^^^^^^^^^

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.

.. code-block:: json

    {
        "operations": {
            "queryTest": {
                "parameters": {
                    "testValue": {
                        "location": "query",
                        "sentAs": "test_value"
                    }
                }
            }
        }
    }

header location
^^^^^^^^^^^^^^^

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.

body location
^^^^^^^^^^^^^

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.

postField location
^^^^^^^^^^^^^^^^^^

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.

postFile location
^^^^^^^^^^^^^^^^^

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.

json location
^^^^^^^^^^^^^

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.

xml location
^^^^^^^^^^^^

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.

responseBody location
^^^^^^^^^^^^^^^^^^^^^

Specifies the EntityBody of a response. This can be used to download the response body to a file or a custom Guzzle
EntityBody object.

No location
^^^^^^^^^^^

If a parameter has no location attribute, then the parameter is simply used as a data value.

Other locations
^^^^^^^^^^^^^^^

Custom locations can be registered as new locations or override default locations if needed.

.. _model-schema:

Model Schema
------------

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
~~~~~~~~~~~~~~~

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.

statusCode location
^^^^^^^^^^^^^^^^^^^

Retrieves the status code of the response.

reasonPhrase location
^^^^^^^^^^^^^^^^^^^^^

Retrieves the reason phrase of the response.

header location
^^^^^^^^^^^^^^^

Retrieves a header from the HTTP response.

body location
^^^^^^^^^^^^^

Retrieves the body of an HTTP response.

json location
^^^^^^^^^^^^^

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.

xml location
^^^^^^^^^^^^

Retrieves a top-level node value from an XML document contained in an HTTP response.

Other locations
^^^^^^^^^^^^^^^

Custom locations can be registered as new locations or override default locations if needed.

Example service description
---------------------------

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:

.. class:: overflow-height-500px

    .. code-block:: json

        {
            "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.

.. code-block:: php

    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.