apigility-powered api's on ibm i
TRANSCRIPT
![Page 1: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/1.jpg)
Apigility-powered API’s on IBM iChuk Shirley
Sabel Steel Service Sure Consulting
![Page 2: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/2.jpg)
Senior Software Engineer
Subject Matter Expert
Founder and Owner
![Page 4: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/4.jpg)
TODAY’S TOPICS• API concepts
• Apigility installation / Server configuration
• Creating RESTful web services
• Sanitizing input
• Using the toolkit
• Error handling
• Tips
![Page 5: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/5.jpg)
WHAT IS AN API?
![Page 6: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/6.jpg)
API TERMINOLOGY
• 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”
![Page 7: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/7.jpg)
API TERMINOLOGY• 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
![Page 8: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/8.jpg)
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
![Page 9: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/9.jpg)
LAYER COMMUNICATION
Presentation layer
HTTP Request
HTTP Response
Application/Domain
layers
Persistence layer
DB Interactions
Web API
![Page 10: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/10.jpg)
APIGILITY INSTALLATION
![Page 11: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/11.jpg)
REQUIREMENTS
• Code Editor (Zend Studio, RDi, Notepad, etc.)
• Zend Server 6 or above running PHP 5.4.8 or above
• PHP Toolkit and XMLSERVICE Library
• REST Client (optional)
• Postman, cURL, etc.
![Page 12: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/12.jpg)
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
![Page 13: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/13.jpg)
LOCAL: RUN PHP LOCALLY
• Download PHP to your local computer
• Manual install
• Homebrew, Vagrant, Macports
• All in one (MAMP, XAMPP, WAMP, etc.)
![Page 14: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/14.jpg)
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
![Page 15: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/15.jpg)
REMOTE INSTALLATION
![Page 16: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/16.jpg)
DOWNLOAD SKELETON APP
• Add Zend Server’s binaries folder to PATH environment variable
• Start PASE shell
![Page 17: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/17.jpg)
VERIFY OPENSSL VERSION• Only recent versions of OpenSSL can properly
use this CA bundle.
• Make sure you’re running at least 0.9.8
Too old!
![Page 18: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/18.jpg)
PHP 5.6 AND OPENSSL
• PHP 5.6 now verifies peer certificates by default
• Download “good known” CA bundle
• Change php.ini setting
![Page 19: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/19.jpg)
RUN APIGILITY INSTALLER
• Rename the directory to AcmeAPI
• Return to PASE and change directories to /www
• Run the Apigility installer scriptphp-cli -r “readfile(‘https://www.apigility.org/install');” | php-cli
![Page 20: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/20.jpg)
SERVER CONFIGURATION
![Page 21: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/21.jpg)
DISABLE OPCACHE• Enable opcache blacklist in php.ini
• Create file opcache_blacklist.txt and add two entries
![Page 22: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/22.jpg)
DISABLE APC CACHE
• Change PHP setting in datacache.ini
• Set zend_datacache.apc_compatibility to “0”
![Page 23: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/23.jpg)
CONFIGURE DIRECTORY PERMISSIONS
• Make /config and /module directories writable by web server
![Page 24: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/24.jpg)
ADD APACHE VIRTUAL 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
![Page 25: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/25.jpg)
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>
![Page 26: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/26.jpg)
http://[server ip]:[port]/
![Page 27: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/27.jpg)
CREATING RESTFUL WEB SERVICES
![Page 28: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/28.jpg)
INITIALIZING THE DB2 TABLE
CREATE TABLE 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), NAME VARCHAR (50), ADDRESS VARCHAR (75) );
![Page 29: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/29.jpg)
DESIGNING THE URIS
HTTP Request Method
Example URI Task
GET /customer Lists all rowsPOST /customer Creates new row in dbGET /customer/{customer id} Fetch a particular row PUT /customer/{customer id} Update row in db
DELETE /customer/{customer id} Remove row from db
![Page 30: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/30.jpg)
USING THE ADMIN INTERFACE
![Page 31: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/31.jpg)
USING THE TOOLKIT
![Page 32: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/32.jpg)
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
![Page 33: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/33.jpg)
ADDING DB2 SERVICE
![Page 34: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/34.jpg)
ADDING DB2 SERVICE
![Page 35: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/35.jpg)
ADDING TOOLKIT SERVICE
![Page 36: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/36.jpg)
PROJECT STRUCTURE
![Page 37: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/37.jpg)
USING THE TOOLKIT
![Page 38: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/38.jpg)
USING THE TOOLKIT
![Page 39: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/39.jpg)
USING THE TOOLKIT (PHP)
![Page 40: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/40.jpg)
USING THE TOOLKIT (CL)
![Page 41: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/41.jpg)
USING THE TOOLKIT (RPG)
![Page 42: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/42.jpg)
USING THE TOOLKIT (RPG)
![Page 43: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/43.jpg)
USING THE TOOLKIT (PHP)
![Page 44: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/44.jpg)
ERROR HANDLING
![Page 45: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/45.jpg)
ERROR HANDLING• Use HTTP response status codes for errors • Apigility supports API Problem format
• Uses application/problem+json mediatype
![Page 46: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/46.jpg)
SENDING THE API PROBLEM• You can produce an API Problem with one of two
methods:
• return new \ZF\ApiProblem\ApiProblemResponse()
• throw new Exception()
![Page 47: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/47.jpg)
THROWING AN EXCEPTION
![Page 48: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/48.jpg)
THROWING AN EXCEPTION
![Page 49: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/49.jpg)
CUSTOMERRESOURCE::FETCH()
![Page 50: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/50.jpg)
![Page 51: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/51.jpg)
![Page 52: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/52.jpg)
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/
![Page 53: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/53.jpg)
QUESTIONS?
![Page 54: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/54.jpg)
BONUS!
![Page 55: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/55.jpg)
TIPS
• Start with a small project
• Use Toolkit’s HTTP transport to run PHP locally and RPG remotely
• Abstract the Toolkit calls
![Page 56: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/56.jpg)
“BEST PRACTICE”
• Create ZF2 module to encapsulate Toolkit
• Composer package or php require()
• Move Toolkit calls to domain (e.g., customer) module
• Use DTO instead of array
![Page 57: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/57.jpg)
“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
![Page 58: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/58.jpg)
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.
![Page 59: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/59.jpg)
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
![Page 60: Apigility-powered API's on IBM i](https://reader034.vdocuments.us/reader034/viewer/2022042515/587b20f01a28ab736c8b68d7/html5/thumbnails/60.jpg)
THANKS!