This document discusses Apigility-powered RESTful APIs on IBM i systems. It covers API concepts, installing Apigility, creating RESTful web services, using the Apigility toolkit, and error handling. The presentation discusses installing Apigility locally or remotely, designing URI patterns, using the admin interface to create services, adding database and toolkit services, and calling the toolkit from PHP, CL, and RPG code. It also provides tips on best practices like abstracting toolkit calls and using commands and queries.

1. Apigility-powered API’s on IBM i
Chuk Shirley
Sabel Steel Service
Sure Consulting

2. Senior Software
Engineer
Subject Matter Expert
Founder and Owner

3. 2015 Innovation Award
Winner
@ChukShirley chukShirley@gmail.com

4. TODAY’STOPICS
• API concepts
• Apigility installation / Server configuration
• Creating RESTful web services
• Sanitizing input
• Using the toolkit
• Error handling
• Tips

5. WHAT IS AN API?

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

9. LAYER COMMUNICATION
Presentation
layer
HTTP Request
HTTP Response
Application
/Domain
layers
Persistence
layer
DB
Interactions
Web API

10. APIGILITY INSTALLATION

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

15. REMOTE INSTALLATION

16. DOWNLOAD SKELETON APP
• Add Zend Server’s binaries folder to PATH
environment variable
• Start PASE shell

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

20. SERVER CONFIGURATION

21. DISABLE OPCACHE
• Enable opcache blacklist in php.ini
• Create file opcache_blacklist.txt and add two
entries

22. DISABLE APC CACHE
• Change PHP setting in datacache.ini
• Set zend_datacache.apc_compatibility to “0”

23. CONFIGURE DIRECTORY
PERMISSIONS
• Make /config and /module directories
writable by web server

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

25. Listen *:[port]
NameVirtualHost *:[port]
<VirtualHost *:[port]>
ServerName [server ip]:[port]
DocumentRoot "/www/AcmeAPI/public"
!
SetEnv APPLICATION_ENV "development"
AllowEncodedSlashes On
!
RewriteEngine on
<Location />
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
!
RewriteCond %{REQUEST_URI}::$1 ^(/.+)(.+)::2$
RewriteRule ^(.*) - [E=BASE:%1]
RewriteRule ^(.*)$ %{ENV:BASE}index.php [NC,L]
</Location>
</VirtualHost>

26. http://[server ip]:[port]/

27. CREATING RESTFUL
WEB SERVICES

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

30. USINGTHE ADMIN INTERFACE

31. USINGTHETOOLKIT

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

33. ADDING DB2 SERVICE

34. ADDING DB2 SERVICE

35. ADDINGTOOLKIT SERVICE

36. PROJECT STRUCTURE

37. USINGTHETOOLKIT

38. USINGTHETOOLKIT

39. USINGTHETOOLKIT (PHP)

40. USINGTHETOOLKIT (CL)

41. USINGTHETOOLKIT (RPG)

42. USINGTHETOOLKIT (RPG)

43. USINGTHETOOLKIT (PHP)

44. ERROR HANDLING

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()

47. THROWING AN EXCEPTION

48. THROWING AN EXCEPTION

49. CUSTOMERRESOURCE::FETCH
()

52. ADDITIONAL RESOURCES
• This presentation’s GitHub repo:
http://github.com/chukShirley/rpg-php-rest-services-
apigility
• Apigility documentation:
http://www.apigility.org/documentation
• HTTP status codes cheat sheet:
http://httpstatus.es/

53. QUESTIONS?

54. BONUS!

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

60. THANKS!