ApiServicesBundle documentation

Working with API services can be time-consuming, error-prone, and repetitive. The ApiServicesBundle is a Symphony Bundle which aids in the creation and use of commands associated with API endpoints. While simple API calls can be constructed using tools as ubiquitous as curl, or through the construction of :class:`GuzzleHttp` client calls (or other API frameworks), these calls can be made more DRY and reusable by using API Service Descriptions.

In addition, many API data structures resemble “Items” and “Collections of Items”. The ApiServicesBundle provides boilerplate to help quickly organize data returned from an API call and use it logically; this greatly improves the usability–and re-usability–of API data. See ApiServicesBundle Quick Start to get started.

What Is An API Service Description?

The ApiServicesBundle is built on top of guzzle/command and guzzle/services. These two libraries extend guzzle/guzzle which is the REST API framework used to make API calls. Guzzle’s service description files include “operations” which pair a named “command” with parameters (if any) to perform an API call.

According to Guzzle’s documentation:

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.

As you can see, one of the main benefits of an API service description is the ability to document and abstract out different API calls and the parameters available. The ApiServicesBundle makes it easy to use Guzzle’s service description SCHEMA which is inspired by the OpenAPI Specification (hopefully Guzzle will move to the OpenAPI Specification at some point). Specific documentation on a description file’s structure is provided by Guzzle.

How Do I Use These Descriptions?

There is plenty of documentation online showing how to use Guzzle’s service description files and commands so understanding the specifics is left up to the reader. However, the ApiServicesBundle has its own |ServiceClient| which extends the GuzzleClient class provided by guzzle/command. The |ServiceClient| makes it easy to build API service clients with an underlying service description. This is covered in the ApiServicesBundle Quick Start documentation.

Learn More:

• Quickstart
  • Overview
  • The ServiceClient
  • Response Models
  • Caching API Responses
  • Dispatching Events For Extensibility
  • Learn More
• Response Models
  • Introduction
  • AbstractResponseModel
  • AbstractResponseModelCollection
• CacheProvider
• Event System
• Traversing Response Data With dot
  • Introduction
  • Sample Data
  • Using Dot
  • Default Values
• Promises
  • Introduction
  • Example Flow
  • Code Example
  • ApiServiceBundle Promise