{"id":784,"date":"2018-09-22T17:42:16","date_gmt":"2018-09-22T17:42:16","guid":{"rendered":"https:\/\/alexrusin.com\/?p=784"},"modified":"2018-09-23T14:13:08","modified_gmt":"2018-09-23T14:13:08","slug":"api-client-design","status":"publish","type":"post","link":"https:\/\/blog.alexrusin.com\/api-client-design\/","title":{"rendered":"API Client Design"},"content":{"rendered":"<p>When you extensively work with certain APIs, like Shopify&#8217;s for example, you will end up with bunch of functions that map to API&#8217;s endpoints. One of the approaches I have seen so far is to create an API class <b>ShopifyApi<\/b> and make those functions class methods. So it looks something like the figure below.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-785\" src=\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_simple_design.jpg\" alt=\"\" width=\"825\" height=\"291\" srcset=\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_simple_design.jpg 825w, https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_simple_design-300x106.jpg 300w, https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_simple_design-768x271.jpg 768w\" sizes=\"(max-width: 825px) 100vw, 825px\" \/><\/p>\n<p>I see several problems with this approach. First of all it is not really object oriented design. A bunch of functions wrapped in a class are still a bunch of functions. Second, it violates <em>Single Responsibility<\/em> principle. <b>ShopifyApi<\/b> class is obviously trying to do a lot of things. Changes in different areas will require you to change this class. Thirdly, this class is not very testable. It will be hard to test it without hitting an actual API endpoint.<\/p>\n<p>Let&#8217;s make some changes to this class. In PHP we have several ways of sending HTTP request. For example, <a href=\"http:\/\/docs.guzzlephp.org\/en\/stable\/\" target=\"_blank\" rel=\"noopener\">Guzzle<\/a> library, Curl PHP extension, or just simple streams. A good refactor will be to pass a transport into <b>ShopifyApi<\/b> class instead of having transport inside. We can leverage C<em>omposition<\/em> design principle here.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-788\" src=\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_transport_refactored.jpg\" alt=\"\" width=\"801\" height=\"269\" srcset=\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_transport_refactored.jpg 801w, https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_transport_refactored-300x101.jpg 300w, https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_transport_refactored-768x258.jpg 768w\" sizes=\"(max-width: 801px) 100vw, 801px\" \/><\/p>\n<p>By coding to interface we can choose different implementations of the transport and even swap them at run time. Personally I also use couple helper classes to pass data in and out of the transport: <b>Request<\/b> and <b>Response<\/b>.<\/p>\n<p>Now we can use the interface to test our code without hitting an actual API endpoint. We just need to create a fake transport class that implements <em><strong>Transport<\/strong><\/em> interface and returns a dummy data. We can pass this class to <b>ShopifyApi<\/b> when running our tests. In this refactor we use <em>Dependency Inversion<\/em> design principle<\/p>\n<p>Now let&#8217;s split up our <b>ShopifyApi<\/b> &#8220;super class&#8221;. We can take each responsibility this class handles and split them out into their own classes<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-791\" src=\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg\" alt=\"\" width=\"801\" height=\"337\" srcset=\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg 801w, https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored-300x126.jpg 300w, https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored-768x323.jpg 768w\" sizes=\"(max-width: 801px) 100vw, 801px\" \/><\/p>\n<p>This refactor takes advantage of OOP&#8217;s\u00a0<em>Inheritance.<\/em>\u00a0 Depending on responsibilities, parent class can be either abstract or concrete. Child classes can be as small as containing only one method. Don&#8217;t make this fact keep you from refactoring: &#8220;Well, if we extract <b>Fulfillment<\/b> class, it will only have one method, so it is wasteful allocating the whole class to it&#8221;. It may be true now, but later on Shopify will change the way they want you to send fulfillments. For example recently Shopify added locations. Now your <b>Fulfillment<\/b> class has to figure out what location to use when sending a fulfillment. The good thing about it is that you only have to change <b>Fulfillment<\/b> class. Your client code still uses the same interface and does not know about the changes. You can see how <em>Single Responsibility<\/em>\u00a0and\u00a0<em>Encapsulation<\/em> pay off in this case.<\/p>\n<p>In multi tenant applications you may have to use different API credentials for different clients.\u00a0 In this case you can create a some kind of credentials provider.\u00a0 So your design may start looking more like this:<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-794\" src=\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_credentials.jpg\" alt=\"\" width=\"800\" height=\"567\" srcset=\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_credentials.jpg 800w, https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_credentials-300x213.jpg 300w, https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_credentials-768x544.jpg 768w\" sizes=\"(max-width: 800px) 100vw, 800px\" \/><\/p>\n<p>Before you start implementing credentials provider, first think if you really need it. Personally I am against unnecessary complexity and use<em> YAGNI.\u00a0 &#8220;You aren&#8217;t gonna need it&#8221;\u00a0<\/em>is a principle that states functionality should not be added until necessary.\u00a0 If your app does not support multi tenancy chances are it won&#8217;t do it in the future.\u00a0 Multi tenancy requires a different design approach.\u00a0 If your app uses only one set of credentials to connect to Shopify API, keep it simple and don&#8217;t develop unnecessary\u00a0structure to provide credentials to the API client.\u00a0YAGNI.<\/p>\n<p>As you can see, the design can become quite involved.\u00a0 I suggest using common sense when creating an API client.\u00a0 If your app only needs to sync products from Shopify, the suggested design complexity may not be justified.\u00a0 But if there is a lot of stuff going on and your app uses a lot of endpoints, it makes more sense to have a testable design that can accommodate future changes without requiring much work.\u00a0 The more time you invest in building a software, the longer you expect it to live.\u00a0 This means you should be able to easily adapt it to changing requirements and make necessary updates fast.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>When you extensively work with certain APIs, like Shopify&#8217;s for example, you will end up with bunch of functions that map to API&#8217;s endpoints. One of the approaches I have seen so far is to create an API class ShopifyApi and make those functions class methods. So it looks something like the figure below. I&#8230;<\/p>\n","protected":false},"author":1,"featured_media":791,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_kad_post_transparent":"","_kad_post_title":"","_kad_post_layout":"","_kad_post_sidebar_id":"","_kad_post_content_style":"","_kad_post_vertical_padding":"","_kad_post_feature":"","_kad_post_feature_position":"","_kad_post_header":false,"_kad_post_footer":false,"footnotes":""},"categories":[10],"tags":[],"class_list":["post-784","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-php-mysql-development"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v23.7 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>API Client Design | Alex Rusin Blog<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/blog.alexrusin.com\/api-client-design\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"API Client Design | Alex Rusin Blog\" \/>\n<meta property=\"og:description\" content=\"When you extensively work with certain APIs, like Shopify&#8217;s for example, you will end up with bunch of functions that map to API&#8217;s endpoints. One of the approaches I have seen so far is to create an API class ShopifyApi and make those functions class methods. So it looks something like the figure below. I...\" \/>\n<meta property=\"og:url\" content=\"https:\/\/blog.alexrusin.com\/api-client-design\/\" \/>\n<meta property=\"og:site_name\" content=\"Alex Rusin Blog\" \/>\n<meta property=\"article:published_time\" content=\"2018-09-22T17:42:16+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2018-09-23T14:13:08+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg\" \/>\n\t<meta property=\"og:image:width\" content=\"801\" \/>\n\t<meta property=\"og:image:height\" content=\"337\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/jpeg\" \/>\n<meta name=\"author\" content=\"alexrusin\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"alexrusin\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"3 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/#article\",\"isPartOf\":{\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/\"},\"author\":{\"name\":\"alexrusin\",\"@id\":\"https:\/\/blog.alexrusin.com\/#\/schema\/person\/a9005ca622862109b2c514050fbaaf9a\"},\"headline\":\"API Client Design\",\"datePublished\":\"2018-09-22T17:42:16+00:00\",\"dateModified\":\"2018-09-23T14:13:08+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/\"},\"wordCount\":692,\"publisher\":{\"@id\":\"https:\/\/blog.alexrusin.com\/#\/schema\/person\/a9005ca622862109b2c514050fbaaf9a\"},\"image\":{\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/#primaryimage\"},\"thumbnailUrl\":\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg\",\"articleSection\":[\"PHP MySQL Development\"],\"inLanguage\":\"en-US\"},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/\",\"url\":\"https:\/\/blog.alexrusin.com\/api-client-design\/\",\"name\":\"API Client Design | Alex Rusin Blog\",\"isPartOf\":{\"@id\":\"https:\/\/blog.alexrusin.com\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/#primaryimage\"},\"image\":{\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/#primaryimage\"},\"thumbnailUrl\":\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg\",\"datePublished\":\"2018-09-22T17:42:16+00:00\",\"dateModified\":\"2018-09-23T14:13:08+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/blog.alexrusin.com\/api-client-design\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/#primaryimage\",\"url\":\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg\",\"contentUrl\":\"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg\",\"width\":801,\"height\":337},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/blog.alexrusin.com\/api-client-design\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/blog.alexrusin.com\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"API Client Design\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/blog.alexrusin.com\/#website\",\"url\":\"https:\/\/blog.alexrusin.com\/\",\"name\":\"Alex Rusin\",\"description\":\"Web Development Blog\",\"publisher\":{\"@id\":\"https:\/\/blog.alexrusin.com\/#\/schema\/person\/a9005ca622862109b2c514050fbaaf9a\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/blog.alexrusin.com\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":[\"Person\",\"Organization\"],\"@id\":\"https:\/\/blog.alexrusin.com\/#\/schema\/person\/a9005ca622862109b2c514050fbaaf9a\",\"name\":\"alexrusin\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/blog.alexrusin.com\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/c36ef231f9e0b11371891eb84360f4bc?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/c36ef231f9e0b11371891eb84360f4bc?s=96&d=mm&r=g\",\"caption\":\"alexrusin\"},\"logo\":{\"@id\":\"https:\/\/blog.alexrusin.com\/#\/schema\/person\/image\/\"}}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"API Client Design | Alex Rusin Blog","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/blog.alexrusin.com\/api-client-design\/","og_locale":"en_US","og_type":"article","og_title":"API Client Design | Alex Rusin Blog","og_description":"When you extensively work with certain APIs, like Shopify&#8217;s for example, you will end up with bunch of functions that map to API&#8217;s endpoints. One of the approaches I have seen so far is to create an API class ShopifyApi and make those functions class methods. So it looks something like the figure below. I...","og_url":"https:\/\/blog.alexrusin.com\/api-client-design\/","og_site_name":"Alex Rusin Blog","article_published_time":"2018-09-22T17:42:16+00:00","article_modified_time":"2018-09-23T14:13:08+00:00","og_image":[{"width":801,"height":337,"url":"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg","type":"image\/jpeg"}],"author":"alexrusin","twitter_card":"summary_large_image","twitter_misc":{"Written by":"alexrusin","Est. reading time":"3 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/blog.alexrusin.com\/api-client-design\/#article","isPartOf":{"@id":"https:\/\/blog.alexrusin.com\/api-client-design\/"},"author":{"name":"alexrusin","@id":"https:\/\/blog.alexrusin.com\/#\/schema\/person\/a9005ca622862109b2c514050fbaaf9a"},"headline":"API Client Design","datePublished":"2018-09-22T17:42:16+00:00","dateModified":"2018-09-23T14:13:08+00:00","mainEntityOfPage":{"@id":"https:\/\/blog.alexrusin.com\/api-client-design\/"},"wordCount":692,"publisher":{"@id":"https:\/\/blog.alexrusin.com\/#\/schema\/person\/a9005ca622862109b2c514050fbaaf9a"},"image":{"@id":"https:\/\/blog.alexrusin.com\/api-client-design\/#primaryimage"},"thumbnailUrl":"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg","articleSection":["PHP MySQL Development"],"inLanguage":"en-US"},{"@type":"WebPage","@id":"https:\/\/blog.alexrusin.com\/api-client-design\/","url":"https:\/\/blog.alexrusin.com\/api-client-design\/","name":"API Client Design | Alex Rusin Blog","isPartOf":{"@id":"https:\/\/blog.alexrusin.com\/#website"},"primaryImageOfPage":{"@id":"https:\/\/blog.alexrusin.com\/api-client-design\/#primaryimage"},"image":{"@id":"https:\/\/blog.alexrusin.com\/api-client-design\/#primaryimage"},"thumbnailUrl":"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg","datePublished":"2018-09-22T17:42:16+00:00","dateModified":"2018-09-23T14:13:08+00:00","breadcrumb":{"@id":"https:\/\/blog.alexrusin.com\/api-client-design\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/blog.alexrusin.com\/api-client-design\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/blog.alexrusin.com\/api-client-design\/#primaryimage","url":"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg","contentUrl":"https:\/\/blog.alexrusin.com\/wp-content\/uploads\/2018\/09\/api_client_refactored.jpg","width":801,"height":337},{"@type":"BreadcrumbList","@id":"https:\/\/blog.alexrusin.com\/api-client-design\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/blog.alexrusin.com\/"},{"@type":"ListItem","position":2,"name":"API Client Design"}]},{"@type":"WebSite","@id":"https:\/\/blog.alexrusin.com\/#website","url":"https:\/\/blog.alexrusin.com\/","name":"Alex Rusin","description":"Web Development Blog","publisher":{"@id":"https:\/\/blog.alexrusin.com\/#\/schema\/person\/a9005ca622862109b2c514050fbaaf9a"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/blog.alexrusin.com\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":["Person","Organization"],"@id":"https:\/\/blog.alexrusin.com\/#\/schema\/person\/a9005ca622862109b2c514050fbaaf9a","name":"alexrusin","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/blog.alexrusin.com\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/c36ef231f9e0b11371891eb84360f4bc?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/c36ef231f9e0b11371891eb84360f4bc?s=96&d=mm&r=g","caption":"alexrusin"},"logo":{"@id":"https:\/\/blog.alexrusin.com\/#\/schema\/person\/image\/"}}]}},"_links":{"self":[{"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/posts\/784"}],"collection":[{"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/comments?post=784"}],"version-history":[{"count":12,"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/posts\/784\/revisions"}],"predecessor-version":[{"id":830,"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/posts\/784\/revisions\/830"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/media\/791"}],"wp:attachment":[{"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/media?parent=784"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/categories?post=784"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.alexrusin.com\/wp-json\/wp\/v2\/tags?post=784"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}