Thomas Dutrion / @tdutrion - September 2014

Introduction to ApigilityAPI Development made easy

About me

@tdutrion / @engineor / thomas@engineor.com

PHP Fan

Founder and developer/architect at Engineor

Working with Zend Framework since 2009

API based architecture

● Multiplication of the device types and size

● Server side software independent from clients

● Public access to data

=> API-First development: api-first.com

Introduction to Apigility

Implementation issues

● How to standardise an API?

● What are the best practices?

● How to enable multiple clients with a single backend?

=> Read blog.apigee.com

Introduction to Apigility

API basics

Introduction to Apigility

RPC:

Remote Procedure Call is a distributed architecture where a client execute a procedure on a distant machine (server)

Architecture

REST:

Representational State Transfer is an architecture where a client manage distant resources using HTTP verbs.

Introduction to Apigility

Example:GET http://your_api/get-current-time

POST http://your_api/send-email

Example:GET http://your_api/contact

POST http://your_api/contact

GET http://your_api/contact/id

POST http://your_api/contact/id

PUT http://your_api/contact/id

PATCH http://your_api/contact/id

DELETE http://your_api/contact/id

JSON

application/json

{

“name”: “edPug”,

“type”: “meetup”

}

Output format standards

JSON HAL

application/hal+json

{

“_links”: {

“self”: {

“href”: “http://localhost:8000/meetups/1”

}

}

“name”: “edPug”,

“type”: “meetup”

}

Introduction to Apigility

Provide context to the entity / collection, self descriptive API

A tool to build your API

● Generate your project structure

● Leave all the configuration to the

GUI

● Focus on the business layer and only

write the content of your methods

Introduction to Apigility

Apigility has been created by Zend and the community to handle all the non-business code

and configurations

Content negotiation

● Let the user (frontend developer) decide the output type he wants

● Build-in JSON and HAL JSON types, you can add your own

● Based on the accept header

Introduction to Apigility

The documentation is a good example to test different output type on the same resource

Documentation

● Build-in documentation generator

● Can be extended with Swagger for public documentation

● Generated from the fields and constraints given within the GUI

Introduction to Apigility

Documentation is always one of the most important and neglected points in API projectsSelf-descriptive API allow Apigility to build the documentation automatically

application/problem+json

{

“type”: “/api/problems/forbidden”,

“title”: “Forbidden”,

“detail”: “Your API key is missing or invalid.”,

“status”: 403,

“authenticationUrl”: “/api/oauth”

}

Error handling

Introduction to Apigility

https://tools.ietf.org/html/draft-nottingham-http-problem-07

HTTP Problem RFC

● Standard error message

● Use http status code

● Help your frontend developers to

deal with errors

Authentication

● HTTP Simple

● HTTP Digest

● OAuth2

Multiple oauth scenarios, all

described in the documentation

Introduction to Apigility

https://apigility.org/documentation/auth/authentication-about

Versioning

● https://blog.apigee.com/detail/restful_api_design_how_many_versions

● https://blog.apigee.com/detail/api_restful_design_question_verisioning_number_in_the_url

Apigility provides a built in versioning

You can specify the version through url or headers at your convenience

Introduction to Apigility

https://apigility.org/documentation/api-primer/versioning

Concrete introduction to Apigility

History:

● Announced during the ZendCon US in October 2013

● First release 8th October 2013 (version 0.6.0)

● Currently version 1.0.4

Introduction to Apigility

Problems solved:

● Standardising APIs

● Rapid API centric application development

● APIs for file upload as well

● Give access to fast and clean API development for non developers (database connected API)

Installation

● Using Composer

● Using the auto installer

● Using the archive download

● Using the skeleton or as a dependance

Introduction to Apigility

Watch the demo: https://www.youtube.com/watch?v=cE2rwGi437I

Create a database connected API

Introduction to Apigility

Watch the demo: https://www.youtube.com/watch?v=KYsOCCPrOwE

● Use HTTP verbs to query resources

● Fetch automatically data from the table

● The demo does not show a full CRUD, try it yourself, it’s easy!

Add an authentication

● Add an HTTP Basic authentication

● Not very dynamic (requires to change htpasswd for each new user)

● Requires HTTPS

=> good for internal projects or non critical project, prefer oauth in most cases

Introduction to Apigility

Watch the demo: https://www.youtube.com/watch?v=0I_rTFRQid0

Add a version

● Generate new files in background

● Use accept header to select a version

● Use a route parameter to select a version

Introduction to Apigility

Watch the demo: https://www.youtube.com/watch?v=Nt4BNn3QRoQ

Live demonstration

Introduction to Apigility

Questions?

Thanks to:

● Enrico Zimuel / @ezimuel - https://speakerdeck.com/ezimuel/apigility-the-api-builder-for-php

● Enrico Zimuel / @ezimuel - http://goo.gl/io7nqO

● Rob Allen / @akrabat - http://akrabat.com/wp-content/uploads/20140318-phpne-apigility-intro.pdf

Introduction to Apigility

Feel free to comment the presentation: http://www.slideshare.net/engineor/introduction-to-apigility