The document is a presentation on building APIs using Apigility, delivered by Christian Varela, and covers fundamental API concepts such as REST, RPC, and the components of an API-centric system. It explains how Apigility simplifies the creation and maintenance of APIs, provides installation instructions, discusses authentication, error handling, and versioning strategies, and concludes with a demo project. The session aims to enable participants to effectively create and document APIs for various applications.

1. BUILDYOUR APIS WITH .
By ChristianVarela
@gabriel0702
cvarela@conquerorsoft.com
https://joind.in/talk/c35fa
1

2. SLIDES AT:
[LINK]
2

3. CHRISTIANVARELA
• I have a wife and 3 daughters
• I am from Mexico
• Master Degree in Computer Science
• 13 years programming with PHP
• I live in Miami
• I created Conqueror Soft Inc
• I play guitar and piano
3

4. 4

5. Conqueror Soft will take your business to the next Level!
5
www.conquerorsoft.com
info@conquerorsoft.com
facebook.com/conquerorsoft

6. WHAT ISTHIS SESSION ABOUT?
Learn how to take advantage of Apigility to create APIs from scratch or
to expose current functionality from an existent system.You'll learn the
core API concepts, processes, functionality, logic, and in general how you
can create good APIs, including documentation and all the
considerations you must have.
6

7. WHAT ISTHIS SESSION ABOUT?
1. We will define some concepts
1. What is an API?
2. What is REST?
3. What is RPC?
2. How Apigility works (Demo)
7

8. THEORY
8

9. API
Application Programming Interface (API) is a set
of subroutine definitions, protocols, and tools for building application
software
An API is usually related to a software library.
https://en.wikipedia.org/wiki/Application_programming_interface
9

10. API
…web APIs, those delivered over HyperTextTransfer Protocol (HTTP).
For this specific case, then, an API specifies how a consumer can
consume the service the API exposes: what URIs are available, what
HTTP methods may be used with each URI, what query string
parameters it accepts, what data may be sent in the request body, and
what the consumer can expect as a response.
https://apigility.org/documentation/api-primer/what-is-an-api
10

11. REST
Representational state transfer (REST) or RESTful web services is a way
of providing interoperability between computer systems on
the Internet.
https://en.wikipedia.org/wiki/Representational_state_transfer
11

12. RPC
In distributed computing, a remote procedure call (RPC) is when
a computer program causes a procedure (subroutine) to execute in a
different address space(commonly on another computer on a shared
network), which is coded as if it were a normal (local) procedure call,
without the programmer explicitly coding the details for the remote
interaction.
https://en.wikipedia.org/wiki/Remote_procedure_call
12

13. API-CENTRIC SYSTEM
In an API-centric system, all the “core functionality” relies on an “API
engine” and that functionality is provided to any sub-system connected
to the engine through API web services.
13

14. APIGILITY
Apigility is an API Builder, designed to
simplify creating and maintaining useful,
easy to consume, and well structured
APIs. Regardless of your experience in API
building, with Apigility you can build APIs
that enable mobile apps, developer
communities, and any other consumer
controlled access to your applications.
14

15. APIGILITY
3 types of APIs:
1. RPC
2. REST (“customized”)
3. DB Connected (“native”)
15

16. REMOTE PROCEDURE CALL (RPC)
RPC is generally characterized as a single URI on which many
operations may be called, usually solely via POST. Exemplars
include XML-RPC and SOAP. Usually, you will pass a structured request
that includes the operation name to invoke and any arguments you
wish to pass to the operation; the response will be in a structured
format.
16

17. REMOTE PROCEDURE CALL (RPC)
1. One service endpoint, many operations.
2. One HTTP method (usually POST).
3. Structured, predictable request format, structured, predictable response
format.
4. Structured, predictable error reporting format.
5. Structured documentation of available operations.
17

18. RPC IN APIGILITY
1. A single service endpoint can react to multiple HTTP methods. Requests
using methods outside those configured result in a 405 Method Not Allowed
status; OPTIONS requests will detail which requests methods are allowed.
2. A single service endpoint can provide multiple representations. By default, we
return JSON.
3. Errors are reported in a consistent fashion (specifically, application/
problem+json.
18

19. REST (CUSTOMIZED)
REpresentational StateTransfer (REST) is not a specification, but an architecture designed around
the HTTP specification.
1. URIs as unique identifiers for resources.
2. Rich set of HTTP verbs for operations on resources.
3. The ability for clients to specify representation formats they can render, and for the server to
honor those (or indicate if it cannot).
4. Linking between resources to indicate relationships. (E.g., hypermedia links, such as those found
in plain old HTML documents!)
19

20. REST IN APIGILITY
1. REST URIs provide access to both "collections" and individually addressable
"entities" from those collections. Each type can specify HTTP request methods
allowed; requests using methods outside those configured result in a 405 Method
Not Allowed status; OPTIONS requests will detail which requests methods are
allowed.
2. By default, we use Hypertext Application Language, which provides both
relational links as well as the ability to embed other addressable resources.
3. Errors are reported in a consistent fashion (specifically, application/problem+json.
20

21. DB CONNECTED (NATIVE)
DB-Connected services are also REST services.They allow you to
specify a database adapter, and then to choose one or more tables to
expose as services. In other words, DB-Connected is more of a rapid
application development (RAD) or prototyping tool.
21

22. APIS BY METHODS
22
Get Post Put Patch Delete
HTTP entity
methods
Yes Yes Yes Yes
HTTP
collection
methods
Yes Yes

23. APIS BY METHODS
23
Get Post Put Patch Delete
HTTP entity
methods
/[api_name]/N /[api_name]/N /[api_name]/N /[api_name]/N
HTTP
collection
methods
/[api_name] /[api_name]

24. HYPERTEXT APPLICATION LANGUAGE
(HAL)
24

25. HAL
1. HAL is a simple format that gives a consistent and easy way to
hyperlink between resources in your API.
2. it will make your API easier to work with and therefore more
attractive to client developers.
3. It's simple enough that you can just deal with it as you would any
other JSON.
25

26. SIMPLE JSON
1 {
2 "0": {
3 "entity_id": "31",
4 "first_name": "Gabriel",
5 "last_name": "Varela",
6 "dob": "1982-07-02",
7 "created_at": null
8 }
9 }
26

27. HALJSON
1 {
2 "_links": {
3 "self": {
4 "href": "http://localhost:8081/authors?page=1"
5 },
6 "first": {
7 "href": "http://localhost:8081/authors"
8 },
9 "last": {
10 "href": "http://localhost:8081/authors?page=1"
11 }
12 },
13 "_embedded": {
14 "authors": [
15 {
16 "entity_id": "31",
17 "first_name": "Gabriel",
18 "last_name": "Varela",
19 "dob": "1982-07-02",
20 "created_at": null,
21 "_links": {
22 "self": {
23 "href": "http://localhost:8081/authors/31"
24 }
25 }
26 }
27 ]
28 },
29 "page_count": 1,
30 "page_size": 250,
31 "total_items": 1,
32 "page": 1
33 }
27

28. 28

29. APIGILITY INSTALLATION
29

30. APIGILITY INSTALLATION
1. composer create-project zfcampus/zf-apigility-skeleton path/to/install
2. cd path/to/install
3. composer development-enable
4. php -S 0.0.0.0:8080 -ddisplay_errors=0 -t public public/index.php
30

31. APIGILITY INTERFACE
31

32. 32

33. VALIDATION
33

34. VALIDATION
1. It uses zf-content-validation module
2. it uses ZF2 input filters
3. it validates POST, PUT and PATCH (not values provided through query)
4. A message can be provided for the inputs that don’t match the validation
5. They are defined in the Fields tab for the service
34

35. 35

36. VALIDATION ERROR RESPONSE
1 {
2 "validation_messages": {
3 "first_name": {
4 "stringLengthTooShort": "Please provide a name
with length between 10 and 30"
5 }
6 },
7 "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-
sec10.html",
8 "title": "Unprocessable Entity",
9 "status": 422,
10 "detail": "Failed Validation"
11 }
36

37. AUTHENTICATION AND
AUTHORIZATION
37

38. AUTHENTICATION AND
AUTHORIZATION
1. Authentication validates that the veracity of an identity
2. Identities are presented through “Authorization” header
3. Guest identity by default
4. Configured in Authentication tab
38

39. AUTHENTICATION AND
AUTHORIZATION
5. Consider thee methods:
1. Basic authentication
2. HTTP Digest authentication
3. OAuth2
39

40. AUTHENTICATION AND
AUTHORIZATION
6. Authorization takes the entity and verifies if it has permissions to
access a resource
7. Authorization uses ZendPermissionsAcl
8. For REST, each method is a resource
40

41. 41

42. UNAUTHORIZED
1 {
2 "type": "http://www.w3.org/Protocols/
rfc2616/rfc2616-sec10.html",
3 "title": "Unauthorized",
4 "status": 401,
5 "detail": "Unauthorized"
6 }
42

43. ERROR HANDLING
43

44. ERROR HANDLING
1. Apigility supports application/problem+json format
2. implemented through zf-api-problem
3. Exceptions are “converted” to API Problems
44

45. ERROR HANDLING
3. information structure:
1. type
2. title
3. status
4. detail
5. instance
45

46. VALIDATION ERROR RESPONSE
1 {
2 "validation_messages": {
3 "first_name": {
4 "stringLengthTooShort": "Please provide a name
with length between 10 and 30"
5 }
6 },
7 "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-
sec10.html",
8 "title": "Unprocessable Entity",
9 "status": 422,
10 "detail": "Failed Validation"
11 }
46

47. UNAUTHORIZED ERROR
1 {
2 "type": "http://www.w3.org/Protocols/
rfc2616/rfc2616-sec10.html",
3 "title": "Unauthorized",
4 "status": 401,
5 "detail": "Unauthorized"
6 }
47

48. DOCUMENTATION
48

49. DOCUMENTATION
1. Set in the service’s Documentation tab
2. For collection and for entity
3. HTML or Swagger format
4. For Methods
5. Generated by configuration
49

50. 50

51. 51

52. 52

53. VERSIONING
53

54. VERSIONING OPTIONS
1. via URI (in the path)
2. via Query parameter
3. Media type (through accept header: application/vnd.status.v2+json)
4. Custom header
5. Hostname
54

55. VERSIONING IN APIGILITY
1. It uses namespaces for different versions
2. URL versioning (path)
3. MediaType
55

56. VERSIONING EXAMPLE
1 GET 8081/v1/authors
2 accept: application/vnd.quotes-api.v1+json
3 host: localhost:8081
56

57. CORS
57

58. CORS
1. Cross-origin resource sharing (CORS) is a mechanism that allows restricted
resources (e.g. fonts) on a web page to be requested from
another domain outside the domain from which the first resource was served…
2. Certain "cross-domain" requests, notably Ajax requests, however, are forbidden
by default by the same-origin security policy.
3. CORS defines a way in which a browser and server can interact to determine
whether or not it is safe to allow the cross-origin request.
58

59. CORS
1. It allows for more freedom and functionality than purely same-origin
requests, but is more secure than simply allowing all cross-origin
requests.
2. The current actively-maintained specification that defines CORS is
the Fetch Living Standard.
59

60. ZFR-CORS
ZfrCors is a Zend Framework 2 module that allow to easily configure
your ZF 2 application so that it automatically builds HTTP responses
that follow the CORS documentation.
60

61. ZFR-CORS.GLOBAL.PHP
<?php
return [
'zfr_cors' => [
'allowed_origins' => [
'http://localhost:1841'
],
'allowed_methods' => ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
'allowed_headers' => [
'Authorization',
'Content-Type',
'Accept',
'X-Requested-With',
],
'allowed_credentials' => true,
],
];
61

62. DEMO
62

63. HTTPS://BITBUCKET.ORG/GABRIEL0702/
QUOTESAPI
63

64. 64

65. ADD NEW API
65

66. 66

67. 67

68. ADD DB ADAPTER
68

69. 69

70. 70

71. CREATE DB CONNECTED AUTHORS
SERVICE
71

72. 72

73. 73

74. CREATE DB CONNECTED QUOTES
SERVICE
74

75. 75

76. API DOCUMENTATION
76

77. 77

78. 78

79. 79

80. 80

81. 81

82. ADDING AUTHORIZATION
82

83. 83

84. 84

85. QUESTIONS?
85

86. THANKYOU
https://joind.in/talk/c35fa
86