An intuition pump: APIs as cognitive tool — Part 2
meaning and concepts in programmatic interfaces
Please see Part 1 for the introduction to this section.
Keeping in mind the concepts we aknowledged in The Two Black-Boxes Experiment (Dennett, 2010) in Part 1, we can try to see the structure of the client-server system we propose at Hydra Ecosystem through the lenses of those concepts.
IV. The basic tools we are developing, thanks to the students that decide to dedicate their internships to this effort, are: a server (hydrus), a client (agent); this are quite common piece of software that have been integrate to leverage the W3C Hydra standard (currently a draft). This implies that the server and the client share a common semantic representation of the data they exchange; this representation is called ApiDoc (expressed in JSON-LD, it is a machine-readable text format much like an instance of OpenAPI specification).
The ApiDoc is defined by the API designer using the standard specification, you can see an example of a it here:
{ “@id”: “vocab:Command”,
“@type”: “hydra:Class”,
“description”: “Class for drone commands”,
“supportedOperation”: [
{ “@type”: “http://schema.org/FindAction”,
...
}
}code snippet 1: the `/command` endpoint for a drone-regulating API, it allows issuing a “find” command according to the find action as defined in the schema.org vocabulary. Every client connecting to the API knows what “find” “means” as the definition points to a common well-established vocabulary.
The ApiDoc lists all the endpoints and the verbs accepted by the interface, it is a comprehensive semantic representation of the data accessible via the API as allow semantic linking to existing data clouds like DBpedia or Schema.org and all the ones listed as public Linked Data clouds (a visual representation here).
V. In the simulated/computed world of our Web API distributed system, the ApiDoc is the shared representation of the world, we use the language of the Hydra specification to describe the relations among classes of objects, with the relevant relations involved in our simulation. The black-boxes designers share the representation of the world expressed in the ApiDoc; our client and server are the two black-boxes, they may have been developed by very different people from very distant places but rely on a common structure to represent the concepts they use to exchange data around (these structures are, in general, the whole stack of protocols required by a compliant Web request plus, in particular, the ApiDoc that add the semantic description for particular API).
Our server (hydrus) can appear to a client as a “syntactic engine”; it stores data in a very specific format (SQL), its function is to produce/provide records (data/patterns) via the structured membrane of the API. It is a storage of causal regularity from diverse sources (all the clients that post data to it). The advantage of using the ApiDoc in this component is to provide a structured way of deploying the component but also a way of publishing pathways for storing/retrieving data points.
Our client (agent) is a kind of observer of a what is happening in the server, as it is its function (inside a bigger program) to provide connectivity and data to the caller. The agent share the representation of the world with the server and with its API designers, but also a representation (in our case a graph) of the relations in place in the server’s data; the client overlaps the information in the ApiDoc with the cache it keeps when requesting data from the server, to create its own artificial intentional stance on the specific domain of the API.
The manifestation of the system are usual Web requests to store/retrieve data from a server (the system also allow polling but it is an optional optimisation) but there is a level of structured abstraction involved that allows more flexible querying of multiple data sources compared to a non-semantic Web API. This is sorta a good way of trying to explain the possibilities of Semantic Web technologies. Thanks to our contributors, Hydra Ecosystem tools are going to allow a client to connect to multiple servers and build its own narrow stance about the particular domain of the APIs involved; we think that the resulting graph will allows the agent to provide more responsive and flexible querying and in the long term Web APIs with better ergonomicity and developing experience.
The semantic layer on top of the APIs extends the intentional stance of the designer/developer in the sense that encompass his/her activities to allow, among others, a more effective test perimeter of possible event, more fluency in modeling data and data streams, modular and configurable query tactics as the actual querying takes place in the client’s graph completely decoupled from server operations.
If you are interested in contributing or just discussing, please join our Slack channels.
