Blog

Read About What We Love: Web Development & Technologies

Apigility by Zend Framework: No Better Way To Create High Quality APIs

 Earlier, I found it difficult to create APIs for sharing information across multiple platforms. They needed to be rewritten every time for different platforms or devices. Multiple versions had to be maintained as well, this was time consuming. Later, when I had a chance to use ZF2’s Apigility for creating APIs I could see the advantages it brought. It is designed to simplify creating and maintaining easy to consume, useful and structured APIs. With Apigility, you can build APIs that enable mobile apps, developer communities, and any other consumer controlled access to your applications. It is built with ZF2 that extends flexibility to create APIs for PHP without using framework.

Let me take you through the features that make Apigility so effective in creating APIs -

Remote Procedure Call (RPC) and Representational State Transfer (REST)

RPC in Apigility

Apigility provides RPC services with a few different characteristics:

  • A single service endpoint can react to multiple HTTP methods. Requests using methods outside those configured result in a 405 Method Not Allowed status; OPTIONS requests will detail which requests methods are allowed.

  • A single service endpoint can provide multiple representations. By default, we return JSON.

  • Errors are reported in a consistent fashion (specifically, application/problem+json).

APIGILITY allows RPC services to provide multiple representations and even performs hypermedia linking when desired.

REST in Apigility

  • REST URIs provides access to both "collections" and individually addressable "entities" from those collections. Each type can specify HTTP request methods allowed; requests using methods outside those configured result in a 405 Method Not Allowed status; OPTIO

  • NS requests will detail which requests methods are allowed.

  • By default, we use Hypertext Application Language, which provides both relational links as well as the ability to embed other addressable resources.

  • Errors are reported in a consistent fashion (specifically, application/problem+json).

JSON (HAL) as default format

JSON does not provide hypermedia linking by default, so one of the solutions being Hypermedia Application Language (HAL). The specification for this comes in both XML and JSON variants. Links and embedded resources fall under reserved keys; otherwise, you return whatever you want in the payload, however you want. Apigility chose to use HAL, due to its simplicity. It manages to provide the hypermedia controls in a straight-forward way, and does not complicate the payload with additional details, or nest the important bits - the data - several layers deep.

Error handling (API Problem)

API Problem goes by the media type application/problem+json; interestingly, there is also an XML variant, though Apigility does not provide support for it at this time.

The payload of an API Problem has the following structure:

  • Type: A URL to a document describing the error condition (optional, and "about:blank" is assumed if none is provided; should resolve to a human-readable document; Apigility always provides this).

  • Title: A brief title for the error condition (required; and should be the same for every problem of the same type; Apigility always provides this).

  • Status: The HTTP status code for the current request (optional; Apigility always provides this).

  • Detail: Error details specific to this request (optional; Apigility requires it for each problem).

  • Instance: URI identifying the specific instance of this problem (optional; Apigility currently does not provide this).

As part of the Zend certified Engineers team at Gaja Digital, I have listed out the first part of the key Apiglity features in order to help you build better APIs. More ZF2’s Apigility benefits are to follow in our next article. To understand how it can complement your business, feel free to get in touch and our team will be happy to guide you.

Vivek GovindarajanZend PHP Certified Expert

Image Credits to: "http://www.freepik.com/free-photos-vectors/hand" Hand vector designed by Rosapuchalt - Freepik.com

Leave A Comment

Bangalore – Paris – Aix-en-Provence – Geneva – Montreal

We love diversity and we work out of five fabulous cities, on 3 continents, and 3 time zones.


Contact us
We’ll get in touch with you ASAP!