EMEA PUG Presentation in Dublin 2018 Takeaways: - Value of APIs - API best practices - APIs in Progress

1. GREAT APIs – FUTURE OF YOUR PROGRESS APP
Gabriel Lucaciu
Delivery Manager
YONDER
DUBLIN
2018

2. GOALS
Value of APIs
API best practices
APIs in Progress

3. FIRST, LET US KNOW EACH OTHER
12 yrs+

4. MY COMPANY
EXPERIENCE SERVICES NEW INITIATIVES
MODERNISATIONS
APPLICATION MANAGEMENT
GO MOBILE
S
O
L
U
T
I
O
N
S
Agile
coaching https://tss-yonder.com/
&
Automation

5. Intro to APIs
Web resources and operations
URI best practices
REST APIs for OpenEdge
More questions & (I hope) Answers
Agenda

6. APIs

7. API ?
❑ API = APPLICATION PROGRAMMING INTERFACE*
o a set of:
o subroutine definitions
o communication protocols
o and tools for building software
o a set of clearly defined methods of communication among various components
o makes it easier to develop a computer program by providing all the building blocks
❑ An API may be for a:
o web-based system
o operating system
o database system
o computer hardware
o software library
❑ API is the answer to “Business agility” as it allows to build
rapidly new GUI for upcoming devices
* https://en.wikipedia.org/wiki/Application_programming_interface

8. API COMPONENTS
-----
-----
-----
-----
API
Business
logic
Server
Client
Native/Interprocess

9. EVOLUTION OF APIs
1995 2000
2009
2018
Future

10. EVOLUTION OF APIs
1 299 593 865
1546
2418
3422
7182
10302
12649
14600
16061
0
5000
10000
15000
20000
2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016
No. of Public APIs since 2005*
* https://www.programmableweb.com/news/programmableweb-api-directory-eclipses-
17000-api-economy-continues-surge/research/2017/03/13

11. REST vs SOAP: SIMPLICITY WINS AGAIN

12. WEB RESOURCES
• Uniform Resource Identifiers (URIs)
• HTTP Methods & Statuses

13. WEB RESOURCES
o A web resource, or simply resource, is any identifiable thing, whether digital, physical, or abstract.
Resources are identified using Uniform Resource Identifiers.*
o To guarantee uniformity, all URIs follow a predefined set of syntax rules, but also maintain extensibility
through a separately defined hierarchical naming scheme.
o eg: https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top
* https://en.wikipedia.org/wiki/Web_resource

14. WEB RESOURCES
o https://api.taskmgm.com/createCompany
o https://api.taskmgm.com/deleteCompany
o https://api.taskmgm.com/getCompany
o https://api.taskmgm.com/getAllCompanies
o https://api.taskmgm.com/getAllProjects
o https://api.taskmgm.com/getProject
o https://api.taskmgm.com/createProject
o https://api.taskmgm.com/updateProject
o https://api.taskmgm.com/deleteProject
o https://api.taskmgm.com/createLog
o https://api.taskmgm.com/updateLog
o https://api.taskmgm.com/deleteLog
o https://api.taskmgm.com/getLogs
o https://api.taskmgm.com/getLog

15. WEB RESOURCES
/{colections}
contain->
/{stores}
store->
/{documents}
have the actual
data

16. WEB RESOURCES
/projects
- collection
- list of projects
/favorites
- a store
- returns also a
list
- with the
favorite projects
/1234
- document
- details favorite
project

17. o https://api.taskmgm.com/v1/projects
o https://api.taskmgm.com/v1/projects/1234
o https://api.taskmgm.com/v1/projects/favorites
o https://api.taskmgm.com/v1/projects/favorites/1234
WEB RESOURCES

18. WEB RESOURCES
/{collections}
contain->
/{stores}
store->
/{documents}
have the
actual data
/{controllers}
model a
procedural
concept

19. WEB RESOURCES
/users
- collection
- list of users
/1234
- document
- details of a
specific user
/resetPassword
- controller
- resets
password

20. o https://api.taskmgm.com/v1/users
o https://api.taskmgm.com/v1/users/1234
o https://api.taskmgm.com/v1/users/1234/resetPassword
WEB RESOURCES

21. HTTP METHODS – OPERATIONS ON RESOURCES
Resource GET
Reads
PUT
Updates
POST
Creates
DELETE
Deletes
/companies 200 OK
Retrieves the
list of
companies
405 Method
Not Allowed
or 200 OK
Updates full list
of companies
201 Created
Creates a new
company
405 Method
Not Allowed
or 200 OK
Nothing or
deletes the
entire list of
companies
/companies/12
34
200 OK
Retrieves
details about
company 1234
200 OK
Updates
company 1234
if exists, else
error: 404 Not
Found
405 Method
Not Allowed
or
404 Not
Found
200 OK
Deletes
company 1234
sau 404 Not
Found if it
does not exist

22. ❑ Used to retrieve the state of a resource
❑ Request can contain headers but not body
❑ Repeated GET requests must not have side-effects / lead to
changes of the state of a resource
❑ Caches depends on the ability to retrieve a response without
contacting the original server anymore
HTTP Methods / GET

23. ❑ Same as GET, but returns only the headers and not the body
❑ Used to check the existence of a resource or metadata
connected to it
HTTP Methods / HEAD

24. ❑ Used for insert and updates
❑ Message needs to contain a representation of the resource
that client want to store on the server
❑ Content of the message might not be identical with what a
GET request would return. It might contain just the mutable
values / variables from the resource state
HTTP Methods / PUT

25. ❑ Used to create a new resource in a collection
❑ Used to call controllers
❑ Allowed for any action without connection with repeatability
or collateral effects
❑ Not to be used for retrieving / deleting / updating resources
HTTP Methods / POST

26. ❑ Used to delete a resource from a collection
❑ Once the resource is removed using DELETE, it should not
belong anymore to the collection (any GET or HEAD on that
specific resource must end in 404 NOT FOUND)
HTTP Methods / DELETE

27. ❑ Used to get a list of possible operations over a resource
❑ Eg. Allow: GET, PUT, DELETE
HTTP Methods / OPTIONS

28. HTTP STATUSES

29. URI (Uniform Resource Identifier) – BEST PRACTICES

30. ❑ Use nouns at plural and not verbs
o /companies
o /users
o /getUsers
o /getCompanies
❑ Do not mix plural and singular, it’s not consistent
o /companies
o /user
o /users
URI – BEST PRACTICES

31. ❑ Use lowercase characters in URIs
o https://api.taskmgm.com/v1/users
o one resource
o HTTP://Api.Taskmgm.com/v1/users
o same resource as above
o https://api.taskmgm.com/v1/Users
o another resource
❑ Why?
o RFC 3896 defines URIs case sensitive except for the protocol and host components
o scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
URI – BEST PRACTICES

32. ❑ Forward slash separator (/) indicates hierarchical relationships
o http://example.org/vinzari/2012/08/01
❑ Trailing forward slash (/) should not end an URI
o http://example.org/companies/1234/
o http://example.org/companies/1234
❑ Why?
o It doesn’t add semantic value
o Could create confusion (2 different URIs must refer to 2 different resources)
URI – BEST PRACTICES

33. ❑ Hypens (-) could be used to improve URI’s readability
o http://example.org/blogs/gabriel-lucaciu/entry/first-post
❑ Underscore (_) should not be used
o Links are usually displayed with underline; in that case the underscore could be
confused
URI – BEST PRACTICES

34. ❑ Search queries:
o Either through controller
o https://api.taskmgm.com/v1/companies/search
o Or hide complexity behind the «?»
o https://api.taskmgm.com/v1/companies?search=Yonder
❑ Pagination:
o Hide complexity behind the «?»
o https://api.taskmgm.com/v1/companies?limit=10&offset=0
o Can use limit and offset
o Have default values for them
URI – BEST PRACTICES

35. ❑ API versioning:
o No versioning - Adding content to existing resources might not present a breaking change
o https://api.taskmgm.com/companies
o URI versioning - Each time you modify the web API or change the schema of resources, you
add a version number to the URI for each resource
o https://api.taskmgm.com/v1/companies
o Query string versioning - has the semantic advantage that the same resource is always
retrieved from the same URI, but it depends on the code that handles the request to parse the
query string and send back the appropriate HTTP response.
o https://api.taskmgm.com/companies?version=1
o Header versioning - This approach requires that the client application adds the appropriate
header to any requests, although the code handling the client request could use a default
value (version 1) if the version header is omitted.
o GET https://api.taskmgm.com/companies HTTP/1.1
Custom-Header: api-version=1
URI – BEST PRACTICES

36. REST APIs for OpenEdge
• REST Service Interface Options for OpenEdge
• Service Interface Approaches
• Standardized REST (OData)

37. REST SERVICE INTERFACE OPTIONS FOR OPENEDGE
JSDO REST
Service Interface
Options
Data Object
Services (using
REST transport)
Data Object
Services (using
WEB transport)
Custom REST
Service Interface
Options
Mapped RPC REST
Service (using
REST transport)
Custom/DIY
WebHandler (using
WEB transport)
Data Object
Handler
WebHandler (using
WEB transport)
Standardized
REST Service
Interface Options
OData view of
OpenEdge (using
Hybrid Data
Pipeline)

38. SERVICE INTERFACE APPROACHES
Data Object
(REST)
Formerly Mobile
Services
Annotate certain
methods (w/
particular signatures)
Very prescriptive:
Programming model,
URI paths
Uses REST
transport
Creates Data Service
Catalog as public API
Data Object
(WebHandler)
OE v11.6.3
Annotate certain
methods (w/
particular signatures)
More flexibility in
mapping
Uses WEB transport
Requires PAS for
OpenEdge
REST (Mapped
RPC)
Formerly REST
Services
Graphical mapping
tool
Uses REST transport
Flexible in URI
paths
WebHandler
OE v11.6.3
Associate an OOABL
WebHandler class
with a URI pattern
Uses WEB transport
Requires PAS for
OpenEdge
VERY flexible
Do whatever you
want in code/ABL
DataObjectHandler
OE v11.7
Pre-built generic
WebHandler
Mapping defined in
JSON file
VERY Flexible
Requires PAS for
OpenEdge

39. ODATA
❑ OData (Open Data Protocol) is an ISO/IEC approved (2017), OASIS standard (2014) that
defines a set of best practices for building and consuming RESTful APIs
❑ OData is the standard for REST
❑ Key features:
o The OData Data Model - Resources are defined in a data model
o The OData Protocol - URIs to identify resources and query data
o OData Client Libraries - OData libraries enable you to quickly and easily access and
produce OData APIs
❑ It is built on technologies like HTTP, ATOM/XML and JSON.
❑ Defines a template for the datamodel
❑ GET: https://api.taskmgm.com/v1/companies?$top=20&$orderby=Name

40. ODATA EXAMPLE
❑ Requesting an Individual Entity by ID
o The request below returns an individual entity of type Person by the given UserName
"russellwhyte"
o GET serviceRoot/People('russellwhyte’)
❑ Example Response Payload
{
"@odata.context": "serviceRoot/$metadata#People/$entity",
"@odata.id": "serviceRoot/People('russellwhyte')",
"@odata.etag": "W/"08D1694BF26D2BC9"",
"@odata.editLink": "serviceRoot/People('russellwhyte')",
"UserName": "russellwhyte",
"FirstName": "Russell",
"LastName": "Whyte",
"Emails": [
"Russell@example.com",
"Russell@contoso.com"
],
"AddressInfo": [
{
"Address": "187 Suffolk Ln.",
"City": {
"CountryRegion": "United States",
"Name": "Boise",
"Region": "ID"
}
}
],
"Gender": "Male",
"Concurrency": 635404797346655200
}

41. ODATA QUERY OPTIONS
System Query
Option
Description SQL Construct
$filter Restrict the entities returned when querying an entity set to
those matching the filter criteria
WHERE clause
$select Specify the properties to be included in the returned entities SELECT list
$orderby Specify the sort order of the returned entities ORDER BY clause
$expand Include related entities and complex types nested in the
returned entities
INNER JOIN
$top and $skip Enable client to page through results TOP/SKIP or LIMIT/OFFSET
$count Include the count of the number of entities returned in the
result
COUNT(*)
$search Restrict the entities returned when querying an entity set to
those matching the search expression
Full Text Search
$format Specify the desired data format for the response N/A

42. ODATA & PROGRESS

43. ODATA & PROGRESS

44. HYBRID DATA PIPELINE
❑ Hybrid Data Pipeline is a lightweight, embeddable
hybrid data access service, hosted on Progress servers
❑ Provides direct SQL (ODBC or JDBC) or REST (OData)
standards-based data access for hybrid cloud and on-
premises architectures
❑ Uses OpenEdge JDBC driver. It works on any OE
version that supports JDBC
❑ Creates an Odata service based on selected
tables/fields. No code written, just configurations.
❑ How Hybrid Data Pipeline Works:
o Firewall-friendly connectivity
o Standard SQL/REST access
o Single interface to cloud data sources

45. HYBRID DATA PIPELINE

46. RESOURCES
● Odata.org
https://www.odata.org/
● OData 2 and OData 4 for Any Data Source Through Simple Clicks
https://www.progress.com/odata
● What is OData? REST Easy with Our Quick Guide
https://www.progress.com/blogs/what-is-odata-rest-easy-with-our-quick-guide
● OData FAQs: Why should REST API Developers use OData?
https://www.progress.com/blogs/odata-faqs-why-should-rest-api-developers-use-odata
● What’s New with OData 4: OData 2 vs OData 4
https://www.progress.com/blogs/whats-new-with-odata-4-odata-2-vs-odata-4
● REST API (OData) for Progress OpenEdge
https://www.progress.com/odata/openedge

47. CONCLUSIONS

48. ANY QUESTIONS ?

49. Thank you.
DUBLIN
2018
CONTACT:
E gabriel.lucaciu@tss-yonder.com l M +40 743232464 l W www.tss-yonder.com
A 77, 21 Decembrie 1989 St., Building A, 1st floor | 400604 Cluj Napoca | Romania