Guzzle Service Descriptions

HTTP Client Manager uses Guzzle Service Descriptions to define all the REST Resources that will be used by our HTTP Client.

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

Let's start creating a Guzzle Service Description for the "posts" endpoint we used in the Introduction section of this guide.

It's usually a good practice creating a new module called %myproject%_services (where %myproject% is just a placeholder for your project name. I'm going to use ACME as the project name) in which putting all the stuffs related to the REST Services you're going to use.

Generate a new module called acme_services and create a new directory called "api" (or any other name you'd prefer) inside the "src" directory of your module (/modules/custom/acme_services/src/api).

Inside the api directory we can now create a new directory called "resources" and a new YAML file called content_services.yml:

name: "[ACME] - Content Services API"
apiVersion: "1.0"
description: "Client wrapper for the Content Services API."
imports:
  - "posts.yml"

• name: Is just the name of the web service.
• apiVersion: Version identifier that the service description is compatible with
• description: Short summary of the web service
• imports: Service description files to include and extend from. The code for "resources/posts.yml", which is referenced in our sample here, is supplied later in this article.

Once done, we should have something like this:

The resources directory is the one in which we'll put all our Service Description files.

Again, you are free to choose the name you prefer for this directory (eg: descriptions or anything else you think could be more appropriate), the important thing you'll have to remember if you are going to change it, is to update the import property contained inside the content_services.yml file.

We are now ready to create our first Guzzle Service Description! Guzzle Service Descriptions structure consists of two main properties:

1. operations: will contain all our "Commands" which are "Key-value pair objects representing an operation of a web service. Commands have a name and a set of parameters."
2. models: Models are used in service descriptions to provide generic JSON/YAML schema definitions that can be extended from or used in $ref attributes. Models are JSON/YAML schema documents and use the exact syntax and attributes used in parameters.

All we need to do, in order to describe our first command (GetPosts), is just to describe it inside the operations parameters. Inside the resources directory let's create a new YAML file called posts.yml that contains the following:

operations:
  GetPosts:
    httpMethod: "GET"
    uri: "posts"
    summary: "Gets the available Posts. It's possible to define a limit and a sorting order."
    parameters:
      limit:
        location: "query"
        description: "The number of posts to be retrieved."
        type: "integer"
        required: true
        default: 5
      sort:
        location: "query"
        description: "The sorting order."
        type: "string"
        required: true
        default: "desc"
    responseModel: "PostsList"

models:
  PostsList:
    type: "array"
    location: "json"
    items:
      "$ref": "Post"

  Post:
    type: "object"
    location: "json"
    properties:
      userId:
        location: "json"
        type: "integer"
      id:
        location: "json"
        type: "integer"
      title:
        location: "json"
        type: "string"
      text:
        location: "json"
        type: "string"

Let's describe this file a bit:

Operations

• httpMethod: HTTP method used with the operation (e.g. GET, POST, PUT, DELETE, PATCH, etc).
• uri: 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: Short summary of what the operation does.
• parameters: Parameters of the operation. Parameters are used to define how the input data is serialized into an HTTP request.
• responseModel: The representation model of the Response we are expecting to receive, defined within the model's property.

Parameters

• name: Unique name of the parameter (implicitly specified by the key of each parameter object).
• location: 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 and formParam.
  • When you're dealing with JSON Requests consider using json as location parameter
  • When you're dealing with XML Requests consider using xml as location parameter
  • When you're dealing with x-www-form-urlencoded Requests consider using formParam as location parameter
• description: Documentation of the parameter.
• type: 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.
• required: Whether or not the parameter is required.
• default: Default value to use if no value is supplied.

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.

And we are done with our first Guzzle Service Description. All we have to do now is to finally create our HTTP Service API to let our Drupal instance know about the existence of the service description we've just created, but we'll see it in the next chapter.