![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>](https://image.slidesharecdn.com/presentation-151027202550-lva1-app6891/85/Apigility-powered-API-s-on-IBM-i-25-320.jpg)
![http://[server ip]:[port]/](https://image.slidesharecdn.com/presentation-151027202550-lva1-app6891/85/Apigility-powered-API-s-on-IBM-i-26-320.jpg)
Apigility-powered API's on IBM i
- 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
- 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
- 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
- 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>
- 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
- 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
- 37. USINGTHETOOLKIT
- 38. USINGTHETOOLKIT
- 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()
- 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!