API Description =============== ApertureDB uses one JSON command API for metadata, graph relationships, media, and vectors. Python and C++ clients send commands with a separate ordered list of binary blobs. Together, the command array and blob list form a query. For connection setup, see the `client setup guide `_. Connector authors can find native framing and HTTP transport details in :doc:`QueryProtocol`. The Basics ---------- The API represents data as objects and connections, and operates on them through commands: .. _objects: * Objects: Each object is a node in the graph. Objects are of one of the following types: - Entity - Image - Video - Blob - Descriptor - BoundingBox - Polygon - Clip - Frame * Connections: represent relationships between objects. * Commands: perform specific actions on objects (Add/Find/Update/Delete) and the database (GetStatus/GetSchema/GetApiSchema). Queries ------- Clients send **queries** through an ApertureDB connector. Each query contains: * a JSON array of one or more commands, serialized as a string; and * an optional array of blobs for binary input. .. _array_of_blobs: The **array of blobs** carries binary data separately from the JSON. Each blob can contain: * An encoded Image (either a complete image, or a frame of a video) * An encoded Video * A feature vector (which is in itself an array of floating point values) * A user-defined blob ApertureDB processes the commands and returns a **response** with two parts: * JSON command results (normally an array aligned with the query; errors can use other envelopes described in :doc:`Responses`), and * an optional array of blobs containing binary results. Graph metadata operations in a query execute in one transaction. Response construction follows that transaction and can perform other work, including access-control changes and media retrieval. A response or delivery failure can therefore occur after writes have committed. See :doc:`Responses` for error phases and retry guidance; an error does not by itself prove that nothing changed. Each command that consumes binary input takes the next blob in command order. Commands using an object URL instead of an uploaded blob do not consume that blob. For example, two ``AddImage`` commands without URLs require two encoded image blobs in the same order. Returned ``blobs_start`` and ``_blob_index`` fields refer to the separate response blob list. The following Python example requires the ``aperturedb`` package, an existing database user with object-create permission, and a local ``luis_profile_photo.jpg`` file. Set ``APERTUREDB_HOST``, ``APERTUREDB_USER``, and ``APERTUREDB_PASSWORD`` in the environment. The second example uses the same connection settings and retrieves the image created by the first. This query creates a person and an image, with a graph connection between them: .. This is Python code, not just json query/response. Query is not tested. .. TESTED_EXAMPLE: API_Description_1 .. code-block:: python import os from aperturedb import Connector db = Connector.Connector(os.environ["APERTUREDB_HOST"], user=os.environ["APERTUREDB_USER"], password=os.environ["APERTUREDB_PASSWORD"]) query = [{ "AddEntity": { "class": "Person", "properties": { "name": "Luis", "email": "luis@aperturedata.io", "id": 30 } } },{ "AddImage": { "properties": { "description": "profile photo", "year_captured": 1990 } } }] # Because we are inserting an image, a blob is expected # in the blob_array with open("luis_profile_photo.jpg", "rb") as fd: image = fd.read() blobs_array = [image] # Execute the transaction response, blobs = db.query(query, blobs_array) # response is parsed JSON; use a helper function to # print the JSON array nicely. print(db.get_last_response_str()) print(f"Blobs returned: {len(blobs)}") Output: .. TESTED_EXAMPLE: API_Description_1_response .. code-block:: json [{ "AddEntity": { "status": 0 } }, { "AddImage": { "status": 0 } }] In this example, no blob is returned as a result of the **query**, and the "blobs" variable will be an empty array. Here is another example where the opposite happens: no blob is sent as part of the **query**, but blobs are returned as part of the **response**: .. TESTED_EXAMPLE: API_Description_2 .. code-block:: python import os from aperturedb import Connector db = Connector.Connector(os.environ["APERTUREDB_HOST"], user=os.environ["APERTUREDB_USER"], password=os.environ["APERTUREDB_PASSWORD"]) query = [{ "FindImage": { "constraints": ["$year_captured", "==", 1990], "blobs": True, "results": { "list": ["year_captured", "description"] } } }] # Execute the transaction response, blobs = db.query(query) # response is parsed JSON; use a helper function to # print the JSON array nicely. print(db.get_last_response_str()) # Check the number of returned images: print(f"Number of returned images: {len(blobs)}") Output: .. TESTED_EXAMPLE: API_Description_2_response .. code-block:: json [{ "FindImage": { "status": 0, "blobs_start": 0, "entities": [{ "_class": "Images", "_blob_index": 0, "year_captured": 1990, "description": "profile photo" }], "returned": 1 } }] In this case, the array of blobs ("blobs" variable) will have 1 elements, each of which is an encoded image. Using the API ------------- The Python connector accepts Python lists and dictionaries and returns parsed response data plus a list of binary blobs. Native clients encode the command array as JSON. See :doc:`Responses` for response fields and error handling, and :doc:`parameters/ref` for references between commands.