Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Build your APIs with apigility

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.

  • Login to see the comments

Build your APIs with apigility

  1. 1. BUILDYOUR APIS WITH . By ChristianVarela @gabriel0702 cvarela@conquerorsoft.com https://joind.in/talk/c35fa 1
  2. 2. SLIDES AT: [LINK] 2
  3. 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. 4
  5. 5. Conqueror Soft will take your business to the next Level! 5 www.conquerorsoft.com info@conquerorsoft.com facebook.com/conquerorsoft
  6. 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. 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. 8. THEORY 8
  9. 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. 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. 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. 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. 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. 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. 15. APIGILITY 3 types of APIs: 1. RPC 2. REST (“customized”) 3. DB Connected (“native”) 15
  16. 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. 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. 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. 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. 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. 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. 22. APIS BY METHODS 22 Get Post Put Patch Delete HTTP entity methods Yes Yes Yes Yes HTTP collection methods Yes Yes
  23. 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. 24. HYPERTEXT APPLICATION LANGUAGE (HAL) 24
  25. 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. 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. 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. 28
  29. 29. APIGILITY INSTALLATION 29
  30. 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. 31. APIGILITY INTERFACE 31
  32. 32. 32
  33. 33. VALIDATION 33
  34. 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. 35
  36. 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. 37. AUTHENTICATION AND AUTHORIZATION 37
  38. 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. 39. AUTHENTICATION AND AUTHORIZATION 5. Consider thee methods: 1. Basic authentication 2. HTTP Digest authentication 3. OAuth2 39
  40. 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. 41
  42. 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. 43. ERROR HANDLING 43
  44. 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. 45. ERROR HANDLING 3. information structure: 1. type 2. title 3. status 4. detail 5. instance 45
  46. 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. 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. 48. DOCUMENTATION 48
  49. 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. 50
  51. 51. 51
  52. 52. 52
  53. 53. VERSIONING 53
  54. 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. 55. VERSIONING IN APIGILITY 1. It uses namespaces for different versions 2. URL versioning (path) 3. MediaType 55
  56. 56. VERSIONING EXAMPLE 1 GET 8081/v1/authors 2 accept: application/vnd.quotes-api.v1+json 3 host: localhost:8081 56
  57. 57. CORS 57
  58. 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. 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. 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. 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. 62. DEMO 62
  63. 63. HTTPS://BITBUCKET.ORG/GABRIEL0702/ QUOTESAPI 63
  64. 64. 64
  65. 65. ADD NEW API 65
  66. 66. 66
  67. 67. 67
  68. 68. ADD DB ADAPTER 68
  69. 69. 69
  70. 70. 70
  71. 71. CREATE DB CONNECTED AUTHORS SERVICE 71
  72. 72. 72
  73. 73. 73
  74. 74. CREATE DB CONNECTED QUOTES SERVICE 74
  75. 75. 75
  76. 76. API DOCUMENTATION 76
  77. 77. 77
  78. 78. 78
  79. 79. 79
  80. 80. 80
  81. 81. 81
  82. 82. ADDING AUTHORIZATION 82
  83. 83. 83
  84. 84. 84
  85. 85. QUESTIONS? 85
  86. 86. THANKYOU https://joind.in/talk/c35fa 86

×