6. APITERMINOLOGY
• Examples:
• IBM i OS commands (CRTLIB, DSPJOBLOG)
• jQuery methods (jQuery.ajax(), jQuery.on())
• RPG built-in functions (%DEC, %XLATE)
“An API is a way for two computer applications to talk
to each other over a network using a common
language that they both understand.”
Jacobson, Daniel and Greg Brail. Sebastopol, APIs:A Strategy Guide Sebastopol, CA: O’Reilly Media, Inc., 2012
• API = “Application Programming Interface”
7. APITERMINOLOGY
• API vs Web API
• A Web API is an API accessed over HTTP
• Web service vs Web API
• A web service refers to one or many related API
functions
• A web API is a collection of web services
8. APPLICATION LAYERS
Presentation Application & Domain Persistence
Web (HTML, CSS, JS) PHP Db2
Mobile (Objective C,
Cordova)
CL, RPG, COBOL, Java Sessions
Toaster app SQL Cache
Web API
11. REQUIREMENTS
• Code Editor (Zend Studio, RDi, Notepad, etc.)
• Zend Server 6 or above running PHP 5.4.8 or above
• PHPToolkit and XMLSERVICE Library
• REST Client (optional)
• Postman, cURL, etc.
12. DEVELOPMENT METHODS
• Apigility admin UI runs
locally
• Edit your code locally
• Push changes to server
Local Remote
• Apigility admin UI runs on
server
• Edit your code locally (pull
files from server first)
• Push changes to server
13. LOCAL: RUN PHP LOCALLY
• Download PHP to your local computer
• Manual install
• Homebrew,Vagrant, Macports
• All in one (MAMP, XAMPP,WAMP, etc.)
14. LOCAL: RUN INSTALLATION
SCRIPT
php -r “readfile(‘https://apigility.org/install');” | php
*See Apigility docs for alternative installation methods
Install Apigility
Installation complete.
Running PHP internal web server.
Open your browser to http://localhost:8888, Ctrl-C to stop it.
cd /path/to/project/parent/directory
17. VERIFY OPENSSLVERSION
• Only recent versions of OpenSSL can properly
use this CA bundle.
• Make sure you’re running at least 0.9.8
Too old!
18. PHP 5.6 AND OPENSSL
• PHP 5.6 now verifies peer certificates by default
• Download “good known” CA bundle
• Change php.ini setting
19. RUN APIGILITY INSTALLER
• Rename the directory to AcmeAPI
• Return to PASE and change directories to /www
• Run the Apigility installer script
php-cli -r “readfile(‘https://www.apigility.org/install');” | php-cli
24. ADD APACHEVIRTUAL HOST
• In /www/zendsvr6/conf/httpd.conf
• Template is on next slide
• You’ll need to supply three values:
• Server IP address/DNS (10.x.x.x, 192.x.x.x, subdomain.domain.com)
• Port number **Choose one that isn’t in use**
• Path to the project
• Restart Zend Server
28. INITIALIZINGTHE DB2TABLE
CREATETABLE MY_LIB.CUSTOMERS (
ID BIGINT GENERATED ALWAYS AS IDENTITY
(START WITH 1, INCREMENT BY 1, NO ORDER,
NO CYCLE, NO MINVALUE, NO MAXVALUE,
CACHE 20),
NAMEVARCHAR (50),
ADDRESSVARCHAR (75)
);
29. DESIGNINGTHE URIS
HTTP Request
Method
Example URI Task
GET /customer Lists all rows
POST /customer Creates new row in db
GET /customer/{customer id} Fetch a particular row
PUT /customer/{customer id} Update row in db
DELETE /customer/{customer id} Remove row from db
32. ZF2 SERVICES
• The toolkit should be used as a service
• Services are configured in the Service Manager
• PHP array
• Assembled at runtime from many locations
• Global application services located at
/config/autoload/application.config.php
45. ERROR HANDLING
• Use HTTP response status codes for errors
• Apigility supports API Problem format
• Uses application/problem+json mediatype
46. SENDINGTHE API PROBLEM
• You can produce an API Problem with one of two
methods:
• return new ZFApiProblemApiProblemResponse()
• throw new Exception()
55. TIPS
• Start with a small project
• UseToolkit’s HTTP transport to run PHP locally
and RPG remotely
• Abstract theToolkit calls
56. “BEST PRACTICE”
• Create ZF2 module to encapsulateToolkit
• Composer package or php require()
• MoveToolkit calls to domain (e.g., customer)
module
• Use DTO instead of array
57. “BEST PRACTICE”
• Convert DTO to command/query object
• Build command bus/query bus
• Convert Service to command/query handler object
• Restructure and rename command to reflect user’s
intent
58. REST AND USER INTENT
• REST is great for describing database actions (CRUD)
but usually not for representing user intent
• Which HTTP method describes
Customer::payInvoice()?
• The process of paying an invoice may include creating
db records, updating others, sending emails, and
interacting with another web API.
59. REST AND CQRS
• One solution: build your application as a set of
commands and queries(in the CQRS sense).
• Treat each command/query as an endpoint and use
POST/GET http methods.
• POST http://my.api.com/commands/CustomerPayInvoice
• GET http://my.api.com/queries/FetchActiveCustomers
