The document provides an introduction to Apigility, a framework for API development that simplifies the creation and management of APIs. It covers key aspects such as architecture, output formats, error handling, authentication, and versioning, while emphasizing the importance of documentation and best practices for standardizing APIs. Additionally, it highlights installation methods, the benefits of using Apigility, and provides links to demonstrations and additional resources.

1. Thomas Dutrion / @tdutrion - March 2015
Introduction to Apigility
API Development made easy
updated for

2. About me
@tdutrion / @engineor / thomas@engineor.com
PHP enthusiast
Founder and developer/architect at Engineor
Working with Zend Framework since 2009

3. 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

4. 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

5. API basics
Introduction to Apigility
● Architecture
● Output format standards

6. 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

7. 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

8. 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

9. 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

10. 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 projects
Self-descriptive API allow Apigility to build the documentation automatically

11. 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

12. Authentication
● HTTP Simple
● HTTP Digest
● OAuth2
Multiple oauth scenarios, all
described in the documentation
Introduction to Apigility
https://apigility.org/documentation/auth/authentication-about

13. 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

14. 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)

15. 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

16. 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!

17. 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

18. 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

19. 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!

20. Live demonstration
Introduction to Apigility

21. 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

22. 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