apigility introduction v2 (glasgow php)
TRANSCRIPT
Thomas Dutrion / @tdutrion - March 2015
Introduction to ApigilityAPI Development made easy
updated for
About me
@tdutrion / @engineor / [email protected]
PHP enthusiast
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
● Architecture
● Output format standards
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)
● Skeleton application currently in 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
Quick and dirty example:
Injecting your tools
● Productivity: know your tools
● Apigility provides factories
● Composer is included
Introduction to Apigility
Using Doctrine is officially supported (https://github.com/zfcampus/zf-apigility-doctrine), do not copy this slide example!
Live demonstration
Introduction to Apigility
What’s next?
https://twitter.com/julienguittard/status/574980150409969664
Introduction to Apigility
● Decoupled components
● Release end of 2015
● New version of Apigility using ZF3
HTTP middleware stack (PSR-7)
https://twitter.com/ezimuel/status/562911967149850625
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 http://akrabat.com/wp-content/uploads/2015-02-20-phpuk-apigility.pdf
Introduction to Apigility
Feel free to comment: http://www.slideshare.net/engineor/introduction-to-apigility-v2-glasgow-php