Introduce a specification for API clients

Use the existing Client public interface as a means of defining an
interface for all future API clients which may have differing
implementations.

https://ocramius.github.io/blog/when-to-declare-classes-final/

When trying to write some unit tests for a client class I had to
implement, I found I couldn't mock out the
DominionEnterprises\Api\Client class, since it had a final marker.  This
article suggests providing a public interface for final classes so you
can avoid inheritance issues, but still use composition and programming
to an interface to provide design flexibility.  A side effect of this
also allows mocking of final classes by using the interface instead.

Signed-off-by: Ryan Yakstis <ryan.yakstis@dominionenterprises.com>

Author: Ryan Yakstis

src/Client.php

@@ -9,6 +9,7 @@
  * Client for apis
  */
 final class Client
+    implements ClientContract
 {
     /**
      * Flag to cache no requests

src/ClientContract.php

@@ -0,0 +1,110 @@
+<?php
+namespace DominionEnterprises\Api;
+
+/**
+ * Client for apis
+ */
+interface ClientContract
+{
+    /**
+     * Get access token and refresh token
+     *
+     * @return array two string values, access token and refresh token
+     */
+    function getTokens();
+
+    /**
+     * Search the API resource using the specified $filters
+     *
+     * @param string $resource
+     * @param array $filters
+     *
+     * @return mixed opaque handle to be given to endIndex()
+     */
+    function startIndex($resource, array $filters = []);
+
+    /**
+     * @see startIndex()
+     */
+    function index($resource, array $filters = []);
+
+    /**
+     * Get the details of an API resource based on $id
+     *
+     * @param string $resource
+     * @param string $id
+     *
+     * @return mixed opaque handle to be given to endGet()
+     */
+    function startGet($resource, $id);
+
+    /**
+     * @see startGet()
+     */
+    function get($resource, $id);
+
+    /**
+     * Create a new instance of an API resource using the provided $data
+     *
+     * @param string $resource
+     * @param array $data
+     *
+     * @return mixed opaque handle to be given to endPost()
+     */
+    function startPost($resource, array $data);
+
+    /**
+     * @see startPost()
+     */
+    function post($resource, array $data);
+
+    /**
+     * Update an existing instance of an API resource specified by $id with the provided $data
+     *
+     * @param string $resource
+     * @param string $id
+     * @param array $data
+     *
+     * @return mixed opaque handle to be given to endPut()
+     */
+    function startPut($resource, $id, array $data);
+
+    /**
+     * @see startPut()
+     */
+    function put($resource, $id, array $data);
+
+    /**
+     * Delete an existing instance of an API resource specified by $id
+     *
+     * @param string $resource
+     * @param string $id
+     * @param array $data
+     *
+     * @return mixed opaque handle to be given to endDelete()
+     */
+    function startDelete($resource, $id, array $data = null);
+
+    /**
+     * @see startDelete()
+     */
+    function delete($resource, $id, array $data = null);
+
+    /**
+     * Get response of start*() method
+     *
+     * @param mixed $handle opaque handle from start*()
+     *
+     * @return Response
+     */
+    function end($handle);
+
+    /**
+     * Set the default headers
+     *
+     * @param array The default headers
+     *
+     * @return void
+     */
+    function setDefaultHeaders($defaultHeaders);
+}