HTTP Services API

Now that we have created our Guzzle Service Description for the posts resources, we can finally integrate them within Drupal by creating the HTTP Service API.

HTTP Services API are a Drupal Plugin written in YAML, provided by HTTP Client Manager, used to allow Guzzle to load our Service Descriptions and to configure Guzzle Clients.

Creating an HTTP Service API it's really simple. All we have to do is just create a new YAML file called %my_module%.http_services_api.yml inside the root of our module.

So, let's create a new file called "acme_services.http_services_api.yml" inside our acme_services module:

acme_services.contents:
  title: "[ACME] - Contents Services API"
  api_path: "/src/api/resources/content_services.yml"
  config:
    base_uri: "http://api.example.com"
    debug: "/tmp/http.log"

• acme_services.contents: It's the unique identifier of our HTTP Service API. Since our module could define multiple service APIs, it's a good practice using the module name as a prefix, followed by a dot.
• title: It's a label used to describe the API we are going to use.
• api_path: It's a relative path (starting from the module folder) to the Service Description main file.
• config: It's the config object that will be used to configure our Guzzle client. You can find the full documentation about it here
  • in this example we'll use the debug configuration to redirect debugging output into a file. 

And we have done! If we go now on the HTTP Client Manager administration page ( /admin/config/services/http-client-manager ) we should see something like this:

By clicking on the "View Commands" button of our Service API we'll see all the commands defined within our Guzzle Service Descriptions:

As we can see from the pic above, all the data we put inside the service description is shown inside the GetPosts tab.

Let's add the GetPostComments command defined in the Introduction section now in order to complete our service description.

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"

  GetPostComments:
    httpMethod: "GET"
    uri: "posts/{postId}/comments"
    summary: "Gets a list of all the comments related to the given Post."
    parameters:
      postId:
        location: "uri"
        description: "The Post ID."
        type: "integer"
        required: true
    responseModel: "CommentsList"

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"

  CommentsList:
    type: "array"
    location: "json"
    items:
      "$ref": "Comment"

  Comment:
    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 refresh the HTTP Client Manager administration page and we'll see a new Guzzle Command called GetPostComments being added to the list:

As you can see, this time the parameter is contained inside the URI, so we used the "uri" location in order for Guzzle Service Description to know where to perform the parameter substitution.

Another thing you may have noticed is about the data redundancy contained inside the "models" property. Post and Comment models actually look like having the same structure. So we could optimize that thing but we'll see how to do it in the next chapter.