haveapi 0.26.3 → 0.26.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 740c6f1d16a0878ef9af93f773e58011bf79bed6176f28cce52ca57282bd535f
-  data.tar.gz: 32219b176c9e28199bd6620bd2586186f2f7e3fd558beeaac87b9f18310d953c
+  metadata.gz: 2aaba661c1079ed4477b407baa76f18076b11547db5fde580dc0fefda6af575e
+  data.tar.gz: cef021ca91b4a94357d3dd1d14896cc1cf1058ecb2c8f6eedef8e3ad8cbf32c7
 SHA512:
-  metadata.gz: 4a5f0e2d83de930546bce52593dd5cd40cd20d8399f1fff6a85ed3814a44ed9ae0f4d4ce315ba6deb818db22f755854e1d4cf4de9ec7fe0d8c5f9723b7261392
-  data.tar.gz: d2bcda0de0d624d7c7975d85de15c26ebf0a326fad6458f8bcb6e50160c5efab8f0edfb6a8919f2b2e0aa979c59a6b7fcbfe892f2eeca8dbdf97069e2f7f76cc
+  metadata.gz: 739e1ec05795c57ab4e54cf28b563a711927a23692a1c5070e0ea97adb66fbdde45c88a38f75ed221c88231ae0d3eb7a47f82e425f4712d5dfba56a3a020faae
+  data.tar.gz: f7fbf1852b104206dc050c6456609e36b47a8835a9cfe230d24413739978069259c37bda866119536c23abf2a74e7ee094eab48c8d538981f45e32581a35e494

data/doc/create-client.md

@@ -0,0 +1,107 @@
+# Client definition
+It is necessary to differentiate between clients for HaveAPI based APIs
+and clients to work with your API instance. This document describes
+the former. If you only want to use your API, you should check a list
+of available clients and pick the one in the right language. Only when
+there isn't a client already available in the language you want, then
+continue reading.
+
+# Design rules
+The client must completely depend on the API description:
+
+ - it has no assumptions and API-specific code,
+ - it does not know any resources, actions and parameters,
+ - everything the client knows must be found out from the API description.
+
+All clients should use a similar paradigm, so that it is possible to use
+clients in different languages in the same way, as far as the language syntax
+allows. Clients bundled with HaveAPI may serve as a model. A client should
+use all the advantages and coding styles of the language it is written
+in (e.g. use objects in object oriented languages).
+
+A model paradigm (in no particular language):
+
+    // Create client instance
+    api = new HaveAPI.Client("https://your.api.tld")
+
+    // Authenticate
+    api.authenticate("basic", {"user": "yourname", "password": "yourpassword"})
+
+    // Access resources and actions
+    api.<resource>.<action>( { <parameters> } )
+    api.user.new({"name": "Very Name", "password": "donottellanyone"})
+    api.user.list()
+    api.nested.resource.deep.list()
+
+    // Pass IDs to resources
+    api.nested(1).resource(2).deep.list()
+
+    // Object-like access
+    user = api.user.show(1)
+    user.id
+    user.name
+    user.destroy()
+
+    // Logout
+    api.logout()
+
+# Necessary features to implement
+A client should implement all of the listed features in order to be useful.
+
+## Resource tree
+The client gives access to all listed resources and their actions.
+
+In scripting languages, resources and actions are usually defined as dynamic
+properties/objects/methods, depending on the language.
+
+## Input/output parameters
+Allow sending input parameters and accessing the response.
+
+## Input/output formats
+A client must send appropriate HTTP header `Accept`. As only JSON is by now built-in
+in HaveAPI, it should send `application/json`.
+
+## Authentication
+All authentication methods that are built-in the HaveAPI should be supported
+if possible. The client should choose suitable authentication method
+for its purpose and allow the developer to select the authentication method
+if it makes sense to do so.
+
+It is a good practise to implement authentication methods as plugins,
+so that developers may add custom authentication providers easily.
+
+## Object-like access
+A client must interpret the API response according to action output layout.
+Layouts `object` and `object_list` should be handled as object instances,
+if the language allows it.
+
+Object instances represent the object fetched from the database. Received
+parameters are accessed via object attributes/properties. Actions are defined
+as instance methods. Objects may have associations to other resources which
+must be made available and be easy to access.
+
+# Supplemental features
+Following features are supplemental. It is good to support them,
+but is not necessary.
+
+## Client-side validations
+Client may make use of described validators and validate the input before
+sending it to the API, to lessen the API load and make it more user-friendly.
+
+However, as the input is validated on the server anyway, it does not have
+to be implemented.
+
+## Metadata channel
+Metadata channel is currently used to specify what associated resources should
+be prefetched and whether an object list should contain total number of items.
+
+Metadata is nothing more than a hash in input parameters under key `_meta`.
+
+## Blocking actions
+Useful for APIs with long-running actions. Clients can check state of such actions
+using resource `ActionState`. Because this resource is automatically present in all
+APIs that use blocking actions, client libraries expose this resource to the developer
+just as any other resource in the API.
+
+However, you may wish to integrate it in your client and provide ways for the action
+call to block/accept callbacks.