CInP is a messaging protocol that allows software and systems to communicate via Hypertext Transfer Protocol (HTTP). CInP was created to solve some of the ambiguities with REST and to add a few non CRUD abilities. CInP promotes moving all business logic, data consistancy, and permissions inside the API server.
The examples in the documentation were generated by making requests to the demo poroject. The demo project is found at https://github.com/cinp/demo and can be deployed as either in Docker or Vagrant. Also there is a browser extension at https://github.com/cinp/web_extension which can be installed from source, or aviable at https://chrome.google.com/webstore/detail/cinp-generic-client/lacnhpojnjgdohcdggednghjibhgkeop?hl=en-US&gl=US for chrome. You can view what the browser is sending via the developer console (ctl-shift-i) or use something like wireshark/tcpdump (if the connection is not encrypted).
...
CInP Verbs (or in HTTP Methods)
- DESCRIBE - Describes the endpoint, see DESCRIBE.rst
- GET - Get one or more Objest, see GET.rst
- LIST - Get a List of Objects, see LIST.rst
- CREATE - Create a new Object, see CREATE.rst
- UPDATE - Update one or more Existing Object(s), see UPDATE.rst
- DELETE - Delete one or more Existing Objest(s), see DELETE.rst
- CALL - Invoke an Action on zero, one, or more Object(s), see CALL.rst
- OPTIONS - Tells the browser what Methos are Allowed, and if configured, returns CORS headers
A CInP URI consists of a Scheme, Host, Port, Base Path, Namespace(s), Model, Id and Action:
scheme://host[:port]/root path/[namespace[/namespace...]/][model[:id:[id2:...]][(action)]]
reference python regex:
'^({0}|/)(([a-zA-Z0-9\-_.!~*]+/)*)([a-zA-Z0-9\-_.!~*]+)?(:([a-zA-Z0-9\-_.!~*\']*:)*)?(\([a-zA-Z0-9\-_.!~*]+\))?$'
the {0} is replaced with the root path. The match groups are ( root, namespace, _, model, rec_id, _, action )
NOTE: if the uri ends in / it is a path to a namespace, otherwise it is a path to a model
scheme:
curently supported schemes are http and https. NOTE: HTTP/2 is planed for future versions.
host, port:
hostname/ip address and port of the CInP service
root path:
prefixed to all paths, ie: `/api/v1/`. The root path is path of the root/base Namespace. It has been common pratice to embed the protocol version in the URI (ie: the `v1` of `/api/v1/`), this is allowed and recommended for CInP as well. CInP adds an additional API version header so the client/server can verify the version independantly of the URI/Path.
namespace:
grouping of simmaler and/or related models. This is also handy for layer 7 load balancers to combine multiple backend servers into a simgle service. Each namespace caries it's own API version, enabling seperate namespaces to be intereated seperately from the others. Namespces can be embeded inside of other namespaces.
model:
the identifier of the model to work with. The model inherits the API version of the namespace it resides in.
id:
the id of the object of the model being worked with. Multiple id's can be delimited by `:`. The maximum number of ids that can be used is specified by the `multi-uri-max` paramater of the parent namespace.
action:
the action to call on the model. If a id(s) are specified the method is called on the object. If no ids are specified, the method is `static` and called on the model.
200:
OK/Deleted/Results returned
201:
Created
400:
Bad Request - some type of problem with the request. The response body may be encoded and contain either a map of fields with errors messages for each field in error, and/or a error message.
401:
Invalid Session, the Auth-Id and/or Auth-Token is Invalid
403:
Not Authorized
404:
Not Found - Object or Path was not found
500:
Exception, with the exception detail in the response body. The response may be encoded, if so it may contain an error message, and optionally a stack trace.
NOTE: Headers specific to each Verb are in that Verbs's Documentation.
CInP-Version:
Specifies the CInP Protocol version. It is curently `0.9`
Accept:
Allows the client to specify what encodgins the client accepts. At this end only `application/json` is implemented. If omited the server will pick it's default, or may chose to return a 400.
Content-Type:
The Encoding of the request, curently on `application/json` is implemented.
Auth-Id, Auth-Token:
These twho headers contain the Auth ID and Token used to indicate the session each request belongs to. If one or both of these headers are not specified, the request is considered Anonymous.
Cinp-Version:
See Request Headers Cinp-Version
Cache-Control:
Controls the cacheablility of the response, NOTE: only DESCRIBE and GET curently allow caching.
Content-Type:
The Encoding of the reply, curently on `application/json` is implemented.
Verb:
The Verb that was sent in the request.
Type:
The target type that was specified by the request's Path, can be one of Namespace, Model, or Action
Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Expose-Headers:
Send in response to an OPTION request, for reporting CORS information to the browser/client. KJeep in mind that Methods used here, are CInP Verbs
See types.rst
Use of the HTTP Header Auth-Id and Auth-Token is used to indicate token representing an authenticated session. The means by which the Token is given to the client is not specified. It might be pre-shard via another system, or via a set of designated actions, for example calling a login action (such as /api/v1/Auth/User(login) ), which would return an token.
Cache control will be handled by normal HTTP cache control HTTP header. NOTE: only GET and DESCRIBE can be cached. All other Verbs cary a no-cache header. LIST Requests do not have enough parameter information in the URI to enable reasonable caching.
- Add inline model data, this way a model can be used as a struct.
- A query language so the client can make queries that do not have filters
- Binary/Bas64 encoded Field Type
- Indicate the primary key, helps down stream caching systems