.. L7|ESP Backend API ================== L7|ESP Backend API ================== L7|ESP extensions, such as custom endpoints and expressions, make use of the backend python API. This API is imported from the lab7 namespace. The backend API follows several conventions for consistency. #. The public api methods are declared in ``lab7..api``. For instance, API methods relating to projects are in ``lab7.project.api``. #. Within the modules, each L7|ESP object generally has ``create_``, ``update_``, ``get_``, and ``query_s`` functions availalbe. For instance, ``create_project``, ``update_project``, ``get_project``, and ``query_projects``. Some modules (notably ``lab7.lis.api``) have additional functions available. #. Most API calls deal with "Resource" objects, which have a UUID and an entry in the ``resource`` table. Functions that operate on existing resource objects will accept either a instantiated object or an object UUID. For instance, ``lab7.sample.api.update_sample`` accepts as a first argument either a ``lab7.sample.models.Sample`` object or the UUID one. #. Common arguments: most API calls have a common set of arguments; some may have additional, API-specific options. Common arguments include: * return_dict: A boolean that, if ``True``, means the the data will be returned in a JSON-serializable format, such as a dictionary (create/update/get) or list of dictionaries (query). If ``False``, the data will be returned as a a SQLAlchemy object or a list of SQLAlchemy objects. * session: The SQLAlchemy session, which should normally be the request-associated session. * agent: A Resource or UUID of a resource that is the "actor" in the API call. This is usually the authenticated user for the request. * params: A list of strings or a dictionary with string keys and list, dictionary, or None values. See below for more details * deep_copy: This is an older API argument that is preserved for backwards compatibility. It influences the default set of params. * ignore_deleted: If true, archived objects will not be returned. If false, archived objects may be returned. For instance, if sample "X" has been archived, ``get_sample("uuid of X")`` will raise a ``ResourceNotFound`` exception but ``get_sample("uuid of X", ignore_deleted=False)`` will return the object. .. note:: When writing extensions that require use of the L7|ESP backend APIs, it is best to avoid importing the backend APIs at the extension module top-level. This is because extensions are initialized relatively early in the ESP process lifecycle. Instead, import at the top of an extension function, as: .. code:: python @expression def my_expression(): import lab7.project.api as project_api The params argument ------------------- The ``params`` argument influences the query which is executed and the shape of the return data. For instance, passing ``params=["uuid"]`` will return a minimal set of information, typically restricted to fields available on the core ``resource`` table in the database. All endpoints and objects have a default set of params. ``params`` may be specified as: * list - the list of properties of interest, such as ``params=["uuid", "values"]`` * dict - the keys are the properties of interest, the values may be None, list, or dict. For instance: ``params={"uuid": None}`` is equivalent to ``params=["uuid"]``. A dict is used for nested parameters. For instance, a workflow accepts params; so do the protocols within the workflows, so you might pass: ``params={"uuid": None, "steps": {"uuid": None}}`` or ``params={"uuid": None, "steps": ["uuid"] }`` which would fetch the minimal data for a workflow plus minimal data for the protocols contained by the workflows. Note that ``params`` is not currently an exact descriptor of the return data structure (ie not like graphql). Rather, it provides a set of "hints" to the API endpoint about the type of data you will be accessing so data can be fetched more efficiently. .. note:: New in ESP 3.0, some APIs now accept special forms of the property names, where the name is prefixed by either ``-`` or ``~``. These prefixes are used to specify a delta against the default properties rather than replacing the defaults outright, with ``-`` used to remove a property and ``~`` used to add one (these also work at the REST API level. ``+`` is a reserved character in ``http``, hence the use of ``~``). For instance, ``params=["-steps"]`` indicates "Use the default properties except steps" and ``params=["~steps"]`` indicates "Use the default properties plus steps". Analysis -------- The analysis module handles generating pipeline reports. .. automodule:: lab7.analysis.api :members: Concierge --------- The concierge module handles configuration objects and handle some ESP service-related functionality. Note that configuration objects are not resources. .. automodule:: lab7.concierge.api :members: Container --------- The container API handles L7|ESP containers/locations. .. automodule:: lab7.container.api :members: :undoc-members: Expression ---------- The expression API handles L7|ESP expression functionality, notably evaluating expressions. .. automodule:: lab7.expression.api :members: Inventory --------- The Inventory API handles inventory-related functionality, including: * Customers * Vendors * Services * Service Types * Inventory Item Types * Inventory Items .. automodule:: lab7.inventory.api :members: :undoc-members: L7FS ---- The l7fs module handles ESP's File registry. .. automodule:: lab7.l7fs.api :members: :undoc-members: LIMS ---- The LIMS module handles the LIMS-related objects, including: * SampleSheet (front-end: Worksheet) * Workflow * WorkflowInstance (front-end: Experiment tied to a workflow) * WorkflowChain * WorkflowChainInsance (front-end: Experiment tied to a worflow chain) * Protocol * ProtocolInstance .. automodule:: lab7.lims.api :members: :undoc-members: Main ---- The main module handles common functionality that doesn't fit other places, including executing named queries. .. automodule:: lab7.main.api :members: Notification ------------ The notification module handles sending L7|ESP notifications. Note that notifications are not resources. .. automodule:: lab7.notification.api :members: Param ----- The param API handles param groups. .. automodule:: lab7.param.api :members: Pipeline -------- The pipeline API handles pipeline-related functionality including: * Pipeline * PipelineInstance * Task * TaskInstance .. automodule:: lab7.pipeline.api :members: Projects -------- The projects API handles project objects and related functionality. .. automodule:: lab7.projects.api :members: :undoc-members: Report ------ The report API handles reports and deriviative object types, including Applets and Doclets. .. automodule:: lab7.report.api :members: Resource -------- API ^^^ The Resource API handles core resource operations. Note that many (most) other modules rely on functionality provided by the core Resource module. Most, if not all, ``create_x``, ``update_x``, and ``query_x`` functionlities will call into base Resource-level functions to handle common operations. For instance, filtering by an object's name is normally handled by ``apply_resource_filters`` offered by the core resource API. .. automodule:: lab7.resource.api :members: Utils ^^^^^ In addition to the standard api module, the ``lab7.resource`` package provides some generally useful utility functions such as ``resource_from_uuid``. .. automodule:: lab7.resource.utils :members: Sample ------ Provides entity-related functionality, including: * WorkflowableResource (UI: Entity) * WorkflowableResourceType (UI: EntityType) * WorkflowableResourceClass (UI: EntityClass) Historically, WorkflowableResource was called ``Sample`` and the APIs have retained the nomenclature for backwards compatibility. .. automodule:: lab7.sample.api :members: :undoc-members: Search ------ Provides access to ESP's global search facility. .. automodule:: lab7.search.api :members: User ---- Provides access to ESP's IAM functionality, including: * User * Role * Lab (UI: Workgroup) .. automodule:: lab7.user.api :members: