APIs (Application Programming Interface)

are becoming commonplace

APIs are hard

• Content negotiation

• HTTP method negotiation

• Error reporting

• Versioning

API considerations

• Validation

• Authentication

• Authorization

• Documentation

Other considerations

Sounds difficult….

Here comes to rescue

Apigility - The world's easiest way to create high-quality APIs.

What Is Apigility?

Creating APIs for your applications shouldn't be hard. Apigility is an API Builder, designed to simplify creating and maintaining useful, easy to consume, and well structured APIs. Regardless of your experience in API building, with Apigility you can build APIs that enable mobile apps, developer communities, and any other consumer controlled access to your applications.

Apigility and Zend Framework 2

Apigility can be used to implement APIs in PHP. Apigility is developed using Zend Framework 2, but this doesn't mean you have to use this framework to develop your API. You can use Apigility in any PHP application, using all the libraries and frameworks that you want.

System Requirements

To run Apigility you need PHP 5.3.23 or greater. But PHP 5.4.8+ for serving the admin user interface.

Installation

From the terminal The easiest way to install Apigility is from your terminal, executing the following command: curl -sS http://apigility.org/install | php If you do not have curl installed you can use PHP itself: php -r "readfile('http://apigility.org/install');" | php Otherwise you can install Apigility using one of the alternative following procedures.

Via release tarball Grab the latest release from the Apigility download page. Untar it: tar xzf zf-apigility-skeleton-1.0.0beta1.tgz

Installation

Via Composer (create-project) You can use the create-project command from Composer to create the project in one go: curl -s https://getcomposer.org/installer | php -- php composer.phar create-project -sdev zfcampus/zf-apigility-skeleton path/to/install

Via Git (clone) First, clone the repository: git clone https://github.com/zfcampus/zf-apigility-skeleton.git # optionally, specify the directory in which to clone cd path/to/install At this point, you need to use Composer to install dependencies. Assuming you already have Composer: composer.phar install

Basic Setup

Once you have the basic installation, you need to put it in development mode: cd path/to/install php public/index.php development Now, fire it up! Do one of the following: Create a vhost in your web server that points the DocumentRoot to the public/ directory of the project Fire up the built-in web server in PHP (5.4.8+) (note: do not use this for production!) In the latter case, do the following: cd path/to/install php -S 0.0.0.0:8080 -t public public/index.php You can then visit the site at http://localhost:8080/ - which will bring up a welcome page and the ability to visit the dashboard in order to create and inspect your APIs.

Content Negotiation

content negotiation is the client telling the server what it is sending and what it wants in return, and the server determining if it can do what the client requests. To match the requested representation as specified by the client via the Accept header with a representation the application can deliver. To determine the Content-Type of incoming data and deserialize it so the application can utilize it. POST /foo HTTP/1.1

Accept: application/json

Content-Type: application/json

{ "foo": "bar" }

Error Reporting

API Problem - application/problem+json

{

"type": "/api/problems/forbidden",

"title": "Forbidden",

"detail": "Your API key is missing or invalid.",

"status": 403,

"authenticationUrl": "/api/oauth"

}

HTTP Method Negotiation

POST /albums HTTP/1.1 Content-Type: application/json 405 Method Not Allowed Allow: GET

Versioning by default

Media type: GET /albums HTTP/1.1 Accept: application/vnd.music.v1+json URL-based: /v1/albums

Validation

POST /albums/1 HTTP/1.1 Content-Type: application/json { "title": "" } 422 Unprocessable Entity Content-Type: application/problem+json { "type": "w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "detail": "Failed validation", "status": 422, "validation_messages": { "title": "Invalid title; must be a non-empty string" } }

Authentication

• HTTP Basic and Digest (for internal APIs) • OAuth2 (for public APIs) • Event-driven, to accommodate anything else • Return a problem response early if invalid credentials are provided

Authentication

GET /albums/1 HTTP/1.1

Authorisation: Basic foobar

Accept: application/json

401 Unauthorized

Content-Type: application/problem+json

{

"type": "w3.org/Protocols/rfc2616/rfc2616-sec10.html",

"title": "Unauthorized",

"detail": "Unauthorized",

"status": 401

}

Authorization

GET /albums/1 HTTP/1.1 Accept: application/json 403 Forbidden Content-Type: application/problem+json { "type": "w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "detail": "Forbidden", "status": 403 }

Documentation

• Written within admin while setting up API • Automatically populated via validation admin • User documentation: • apigility/documentation/{API name}/V1 • JSON or HTMl based on accept header • Swagger available too

References

• Apigility official website http://apigility.org/ • Rob Allen

http://akrabat.com/

THANK YOU That’s all for the Introduction to Apigility