API Server ========== The AirPhoton API provides a series of centralized services that enable remote communication and operation AirPhoton Products. The follow sections cover generic API information and details for each of the major API service. Overview -------- The server provides *user* and *group* access to the API services. Each user will have separate accounts, but multiple users can be grouped together. Users can be a member of multiple groups. In addition to the *user* and *group* functionality, the API server provides access to *instruments*, *control* actions, *control responses*, *data*, and instrument *checkins* logs. .. TIP:: Contact support@airphoton.com if user or group changes are needed. The endpoints covered below are for the *API* requests you can make to server. For each request the server may return requested information, accept information provided, or return a URL to request more information. This procedure is very much like a verbal conversation, but the server only uses specific commands and responses. The following sequence diagram illustrates a simple API *conversation*. .. image:: ./media/http-request-diagram.png :scale: 80% :alt: A diagram showing the process flow between two parties, the User and the Server. The User makes a HTTP or API request to the Server. The Server may take time processing the request. Eventually, the Server responds with a HTTP response which is usually textual information. :align: center In many cases, the *processing* action by the server is nearly instant as the request is for basic, stored information. When the request is, for example, a ``control`` request to a remote instrument, there are likely delays as illustrated by the following sequence diagram. .. image:: ./media/http-request-to-instrument-diagram.png :scale: 80% :alt: A diagram showing the process flow between three parties, the User, the Server, and the Instrument. The Instrument is always slow to respond. The User makes a HTTP or API request to the server. The Server needs to contact the Instrument. After a delay, the Instrument responds to the Server, and the Server responds to the User. :align: center The following sections cover the API endpoints to send and request information. Keep these diagrams in mind as you explore each functionality. Getting Started --------------- There are two API servers that can be used. The ``sandbox`` server is intended for short-term testing and development, and the production, ``api`` server is a long-term production setup. Both servers run the same version, when possible, and are encrypted using HTTPS_. The FQDN_ for each server is provided below: - Sandbox Server URL: ``https://sandbox.airphoton.io`` - Production Server: ``https://api.airphoton.io`` .. NOTE:: For training and learning, feel free to use the sandbox server, but be sure to use the production server when managing real site setups and campaigns. The *sandbox* server is rebuilt periodically with default data and without notice. Please, use it for testing only, and do not store important information on that server. Things to Know ~~~~~~~~~~~~~~ All of the examples in this documentation will specify the *sandbox* API server URL. If you want to use the commands in production be sure to change the URL to the *production* API server. Virtually all API service endpoints require user authentication, most examples will have ``[USERNAME]`` and ``[PASSWORD]``. Be sure to substitute your *username* and *password*. More on user credentials below! In a similar way, if other details need to be substituted, those items will also be in brackets also, such as ``[UUID]``. .. TIP:: If you are curious, a UUID_ will be assigned to each server resource so it can be uniquely identified. This is what one would look like: ``b58a8b01-4832-4999-888a-c9617bb7827f`` Many commands and responses will use JSON_, a commondata format which is easily human readable and writable. In this documentation, the JSON is represented with whitespace for added readability, but the real command responses will not have extra whitespace. Finally, the *sandbox* server has specific users, groups, instruments, and more populated by default for testing. Some of the examples in this documentation such as :ref:`users-functionality` below, will return the same or very similar information every time. Other examples, especially new *control* actions commands will return unique UUIDs, and the errors and responses may vary. Be sure to understand how each of these commands work and change! API Versions ~~~~~~~~~~~~ The API URL has a version in the path so future changes can be managed. Currently, the API server only supports ``/v1``. For the *sandbox* server, the base URL is ``https://sandbox.airphoton.io``. Testing the API Server ~~~~~~~~~~~~~~~~~~~~~~ Even before you get user access, the server can be *pinged* to test that the API system is on-line and operational. The following example command sends a simple request to the *sandbox API server*: .. code-block:: bash curl -I https://sandbox.airphoton.io/v1/ping/ The server should return a response similar to below: .. code-block:: console HTTP/2 200 content-type: text/html; charset=utf-8 date: Wed, 01 Jan 2020 00:00:00 GMT server: Caddy server: gunicorn/20.0.4 c-content-type-options: nosniff x-frame-options: DENY content-length: 28 .. TIP:: Try *pinging* the production server by changing the URL! .. NOTE:: While the above example uses the common command line tool, curl_, there are many ways to perform HTTP requests. Another good resource for manual API usage is Postman_. AirPhoton has also provided an example `Python script`_ to demonstrate the API process. API Access ~~~~~~~~~~ Besides the *ping* test, all other API access requires user credentials. This applies to both the *sandbox* and *production* servers. .. TIP:: Contact support@airphoton.com for user access, and be sure to specify the project manager and groups to which you would like access. Pagination ~~~~~~~~~~ The API server uses pagination to break long lists into management data sets. In examples below, you will see this functionality, but consider it as *a page of data at a time*. .. NOTE:: Keep in mind, when you are requesting a specific item (eg. ``GET /instruments/[UUID]``), the server responds with a single object: ``{ ... }`` not a paginated list For all paginated endpoints, accept the following URL query attributes are accepted: :limit: | ``integer`` | the number of responses to send :offset: | ``integer`` | the list position In the example output below (from ``/v1/checkins``), you can see the standardized format. It contains the added attributes from all paginated results. :count: | ``integer`` | the total number of items :next: | ``string`` | the URL to call to navigate forwards in the list :previous: | ``string`` | the URL to call to navigate backwards in the list :results: | ``array`` | the list of data requested .. code-block:: bash :linenos: { "count": 117, "next": "https://sandbox.airphoton.io/v1/checkins/?limit=100&offset=100", "previous" :null, "results": [{ /* controls listed here */ }] } .. _users-functionality: ``users`` Functionality ----------------------- This is an object representing an API *user* account. You can retrieve properties of a *user*. .. sidebar:: ENDPOINTS | **GET** ``/v1/users/:id`` | **GET** ``/v1/users/?:query`` **Attributes** :url: | the full URL representing user *:id* :username: | ``string`` | the accounts username for authentication :email: | ``string`` | the accounts contact email :is_staff: | ``boolean`` | enables Portal access :groups: | ``array of URLs`` | list of accessible API groups Example: Retrieving Your Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves account information for the specified ``:id``. **Command** .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/users/[:id] **Response** .. code-block:: json :linenos: [{ "url": "https://sandbox.airphoton.io/v1/users/3/", "username": "demo@airphoton.io", "email": "", "is_staff": true, "groups": [ "https://sandbox.airphoton.io/v1/groups/1/" ] }] Example: Searching for Your Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves account information by searching for a `username`. **Command** .. code-block:: bash curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/users/?username=[USERNAME] **Response** .. code-block:: json :linenos: [{ "url": "https://sandbox.airphoton.io/v1/users/3/", "username": "demo@airphoton.io", "email": "", "is_staff": true, "groups": [ "https://sandbox.airphoton.io/v1/groups/1/" ] }] .. _groups-functionality: ``groups`` Functionality ------------------------ This is an object representing an API user access *group*. You can retrieve properties of the *group*. .. sidebar:: ENDPOINTS | **GET** ``/v1/groups/`` **Attributes** :name: | ``string`` | the group's name Example: Listing Your Groups ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves a list of your groups. **Command** .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/groups/ **Response** This response uses pagination and returns the result selection as a list under the ``results`` field. .. code-block:: json :linenos: { "count": 1, "next": null, "previous": null, "results": [ { "name": "Demonstration" } ] } .. _instruments-functionality: ``instruments`` Functionality ----------------------------- This is an object representing an AirPhoton *instrument* assigned to your group. You can retrieve and modify properties of the *instrument*. .. sidebar:: ENDPOINTS | **GET** ``/v1/instruments/`` | **GET** ``/v1/instruments/:uuid`` | **GET** ``/v1/instruments/?:query`` **Attributes** :url: | the full URL representing instrument *:uuid* :serial_number: | ``string`` | the instrument's serial number | this acts as the instrument's *username* for the remote access API :name: | ``string`` | a common name for end-user usage :group: | ``string`` | the group URL assigned to the instrument :status: | ``string`` | a status field for end-user usage :info: | ``json object`` | a json object for end-user usage Example: Listing Instruments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves a list of instruments assigned to your groups. **Command** .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/instruments/ **Response** Keep in mind that the returned data structure for searches include pagination and a *results* list. .. NOTE:: In this example, the instrument's *UUID* is located at the end of the returned *url*. ``https://sandbox.airphoton.io/v1/instruments/[UUID]`` .. code-block:: json :linenos: { "count": 2, "next": null, "previous": null, "results": [ { "url": "https://sandbox.airphoton.io/v1/instruments/c2588574-678f-45ad-ab6d-8f5195ce5bb6/", "serial_number": "SS5027", "name": "SS5027", "group": "https://sandbox.airphoton.io/v1/groups/1/", "status": "DEMO", "info": {} }, { "url": "https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/", "serial_number": "SS5013", "name": "SS5013", "group": "https://sandbox.airphoton.io/v1/groups/1/", "status": "DEMO", "info": {} } ] } Example: Accessing a Specific Instrument ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves properties for the specified instrument. **Command** Using an instrument's *id* from the :ref:`Example: Listing Instruments` in the following command: .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/instruments/[UUID]/ **Response** .. code-block:: json :linenos: { "url": "https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/", "serial_number": "SS5013", "name": "SS5013", "group": "https://sandbox.airphoton.io/v1/groups/1/", "status": "DEMO", "info": {} } .. NOTE:: Notice how it is the same information from the prior example, but for only a single requested instrument. For *instruments* this command is not too useful, but when used with *control* actions, *control responses*, *data*, and *checkins*, we can use this method to check the status of a new, specific, pending item. Example: Searching for a Specific Instrument ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves an instrument's properties by searching for its *serial_number*. **Command** Using an instrument's *serial_number* in the following command. If you don't know it, pick one from the :ref:`Example: Listing Instruments`. .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/instruments/?serial_number=[SERIALNUMBER] **Response** The information in this example is the same as if you requested the instrument using *UUID*, but we used the real-life *serial_number* to lookup the details. Keep in mind that the returned data structure for searches include pagination and a *results* list. .. code-block:: json :linenos: { "count": 1, "next": null, "previous": null, "results": [ { "url": "https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/", "serial_number": "SS5013", "name": "SS5013", "group": "https://sandbox.airphoton.io/v1/groups/1/", "status": "DEMO", "info": {} } ] } .. _controls-functionality: ``controls`` Functionality -------------------------- This is an object representing a *control* or command to a remote instrument. Posting a new *control* queues an actions to be send to remote instrumentation. Once created, the returned control's *url* can be monitored for status. .. TIP:: The following *control* examples require a working Communication Module and a connected AirPhoton Instrument to work. The server will accept any valid controls posting, but it will not run until the instrument and communication module check in with the server. If you are testing with your own hardware, please make sure they are properly setup first. .. sidebar:: ENDPOINTS | **GET** ``/v1/controls/`` | **POST** ``/v1/controls/`` | **GET** ``/v1/controls/:uuid`` | **GET** ``/v1/controls/?:query`` **Attributes** :url: | the full URL representing control *:uuid* :instrument: | ``string`` | URL for instrument to control :name: | ``string`` | a common name for end-user usage :status: | ``string`` | allowed: ``new``, ``seen``, ``completed`` | the current state of the control :created_by: | ``string`` | URL for submitting user :command: | ``string`` | the plain-text command to be relayed. See COM100 commands. Example: Sending a Basic Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example posts a new *control* to the server's queue to be issued to the target instrument on the next instrument check-in. Sending *controls* to instruments require creating a JSON object. First we will explore the JSON to be sent, and the actual command. Here is the example JSON object. .. code-block:: json :linenos: { "instrument": "[INSTRUMENT-URL]", "created_by": "[USER-URL]", "name": "api demo", "command":"sendcommand echo Science!" } Lets explore the various components. The ``instrument`` field is the full API server URL for that instrument. Compare this to the command from :ref:`Example: Accessing a Specific Instrument`. The ``created_by`` field is the full API server URL for your user profile. See the command response from `users Functionality`_. You want to supply *your* user profile URL. The ``name`` field is a common name for your reference. The ``command`` field is the command to be sent. In this example, the command is ``sendcommand echo Science!``. .. TIP:: An *echo* command is basically asking the end device to repeat what we say. It is a common way to check connectivity. In this example, we are asking the communication module (``sendcommand``) to ask the instrument the command: ``echo Science!``. The expected result, is the instrument relays *echo Science!* back to the communication module which will then update the remote API server. **Command** .. IMPORTANT:: The following example has issues on Windows for both cmd.exe and PowerShell. If you these systems, look into "Quote Escaping" .. code-block:: bash :linenos: # NOTE: # This command has the [INSTRUMENT-URL] and [USER-URL] pre-populated. # Make sure you change these. # curl --user [USERNAME] \ --request POST https://sandbox.airphoton.io/v1/controls/ \ -H "Content-Type: application/json" \ -d '{"instrument":"https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/","created_by":"https://sandbox.airphoton.io/v1/users/3/","name":"api demo","command":"sendcommand echo Science!"}' .. NOTE:: In the above example, `backslashes`_ are used to spread the command over multiple lines for readability. .. IMPORTANT:: This command is telling the server to do something. While it is a small change, the command uses ``--request POST`` instead of ``--request GET`` as in most other examples. | *POST* is used on an API endpoint to create something. | *GET* is used on an API endpoint to access something. There are more options, but we will use *GET* and *POST* for now. **Response** As covered in :ref:`Things to Know`, this *control* action will generate a new control *UUID* every time! Take note of how your response is different compared to the following example response: .. code-block:: json :linenos: { "url": "https://sandbox.airphoton.io/v1/controls/03654371-4533-47da-943e-b8bd79a86861/", "instrument": "https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/", "name": "api demo", "status": "new", "created_by": "https://sandbox.airphoton.io/v1/users/3/", "command": "sendcommand echo Science!" } .. NOTE:: In the above example, the *UUID* of the *control* is located at the end of *url*. ``https://sandbox.airphoton.io/v1/controls/[UUID]`` Take note how the ``status`` field says *new* immediately after creating the command. We can monitor the *status* field to know when the command has been seen or completed. In the next subsection we will continue this example. Example: Checking the Status of a Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Continuing from the previous subsection, lets explore how to monitor the status of a *control* we created. If needed go back to :ref:`Example: Sending a Basic Command`, and rerun the example. Be sure to copy the ``url`` from the results provided as the *url* will be used in the example below. Also, realize that your URL will differ since the a new UUID is provided every time a control is created. **Command** .. code-block:: bash curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/controls/[UUID] **Response** When the command was first issued, the ``status`` field reported *new*. Depending on how responsive the server and remote communication module are, you may see a few different options. See the Attributes list above. As a result of the above command, the server response shows the command has been completed! .. code-block:: json :linenos: { "url": "https://sandbox.airphoton.io/v1/controls/03654371-4533-47da-943e-b8bd79a86861/", "instrument": "https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/", "name": "api demo", "status": "completed", "created_by": "https://sandbox.airphoton.io/v1/users/3/", "command":"sendcommand echo Science!" } Up to this point, you have been interacting with the API server, but now that the *control* action is *completed*, we have made contact with the remote instrument and likely have a *controlresponse* waiting for us. Checkout `controlresponses Functionality`_ too see how to access the responses resulting from a posted *control*. Example: Listing Controls ~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves a list of controls issued for instrument in your group. **Command** .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/controls/ **Response** Keep in mind that the returned data structure for searches include pagination and a *results* list. .. NOTE:: The following example has been truncated. .. code-block:: json :linenos: { "count": 962, "next": "https://sandbox.airphoton.io/v1/controls/?limit=100&offset=100", "previous": null, "results": [ { "url": "https://sandbox.airphoton.io/v1/controls/873dbfeb-e273-44df-8f7c-b10a3954876a/", "instrument": "https://sandbox.airphoton.io/v1/instruments/c2588574-678f-45ad-ab6d-8f5195ce5bb6/", "name": "api demo", "status": "completed", "created_by": "https://sandbox.airphoton.io/v1/users/3/", "command": "sendcommand echo Science!" }, { "url": "https://sandbox.airphoton.io/v1/controls/b2de5ef3-b55f-47bb-992d-2a9a0056f9b3/", "instrument": "https://sandbox.airphoton.io/v1/instruments/c2588574-678f-45ad-ab6d-8f5195ce5bb6/", "name": null, "status": "completed", "created_by": "https://sandbox.airphoton.io/v1/users/3/", "command": "status" }, { "url": "https://sandbox.airphoton.io/v1/controls/223437c9-7c5c-4642-86fc-76b207de3eb0/", "instrument": "https://sandbox.airphoton.io/v1/instruments/c2588574-678f-45ad-ab6d-8f5195ce5bb6/", "name": null, "status": "completed", "created_by": "https://sandbox.airphoton.io/v1/users/3/", "command": "sendmlcommand ENDSTATUS status" } ] } .. _controlresponses-functionality: ``controlresponses`` Functionality ----------------------------------- This is an object representing a *controlresponse*. The response received after a remote instrument processes a *control*. .. sidebar:: ENDPOINTS | **GET** ``/v1/controlresponses/`` | **GET** ``/v1/controls/:uuid`` | **GET** ``/v1/controls/?:query`` **Attributes** :url: | the full URL representing controlresponse *:uuid* :created_time: | ``ISO-8601 string`` | the UTC time stamp at check-in :control: | ``string`` | URL for linked *control* :error: | ``string`` | optional, error message from remote instrument :response: | ``json object`` | instrument response | currently, only ``text`` string Example: Checking a Control's Response ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example will continue from the above :ref:`Example: Checking the Status of a Command` section. To view the results of the remote command ``sendcommand echo Science!``, we need to request the *controlresponse* related to the *control* action's UUID. If needed go back to :ref:`Example: Sending a Basic Command` and :ref:`Example: Checking the Status of a Command` and rerun the examples. Be sure to copy the ``uuid`` from the ``url`` field in the results provided. **Command** .. code-block:: bash curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/controlresponses/?control=[UUID] **Response** If the *control* action is *completed*, the server will response with the *controlresponse* associated with the *control* UUID. As covered in :ref:`Things to Know`, this *controlresponse*, similar to *control* actions will generate a new *UUID* every time! Take note of how your response is different compared to the following example response: .. code-block:: json :linenos: { "count": 1, "next": null, "previous": null, "results": [ { "url": "https://sandbox.airphoton.io/v1/controlresponses/a13e3b3e-4ca9-492e-b711-a635fc094c97/", "created_time": "2020-11-23T16:58:08.637790Z", "control": "https://sandbox.airphoton.io/v1/controls/873dbfeb-e273-44df-8f7c-b10a3954876a/", "error": "", "response": { "text": "Instrument:echo Science!\r\n" } } ] } Here you can see that there was no ``error``, and that the ``response`` is *Instrument:echo Science!* as expected! .. _checkins-functionality: ``checkins`` functionality -------------------------- This is an object representing a log event when an instrument *checkins* with the remote API server. You can retrieve properties for each *checkins* event. .. sidebar:: ENDPOINTS | **GET** ``/v1/checkins/`` | **GET** ``/v1/checkins/?:query`` **Attributes** :url: | the full URL representing checking event *:uuid* :created_time: | ``ISO-8601 string`` | the UTC time stamp at check-in :instrument: | ``string`` | URL for instrument checking in :control: | ``string`` or ``null`` | optional, URL for associated control handled at check-in Example: Listing Recent Check-ins ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves a list of check-in events for all instruments assigned to your groups. Check-in events are numerous, so the pagination features could be very useful. **Command** .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/checkins/ **Response** .. NOTE:: The following example has been truncated. .. code-block:: json :linenos: { "count": 22053, "next": "https://sandbox.airphoton.io/v1/checkins/?limit=100&offset=100", "previous": null, "results": [ { "url": "https://sandbox.airphoton.io/v1/checkins/6e35c846-da5a-43a0-83ca-a577a9440d6b/", "created_time": "2021-01-20T21:25:51.966667Z", "instrument": "https://sandbox.airphoton.io/v1/instruments/03f91ea5-065b-42c5-8b92-534b7815c423/", "control": null }, { "url": "https://sandbox.airphoton.io/v1/checkins/105b1cb8-e2e0-4f66-bb39-6ff8dd7f4522/", "created_time": "2021-01-20T21:08:05.887223Z", "instrument": "https://sandbox.airphoton.io/v1/instruments/03f91ea5-065b-42c5-8b92-534b7815c423/", "control": "https://sandbox.airphoton.io/v1/controls/6ec7e88d-1400-4eed-98d7-aef431054101/" }, { "url": "https://sandbox.airphoton.io/v1/checkins/5e1e1e07-4720-48a8-9ee1-df57b6cf50d8/", "created_time": "2020-11-24T17:01:43.209274Z", "instrument": "https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/", } ] } Example: Listing Check-ins for an Instrument ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves a list of check-in events for the specified instrument. Check-in events are numerous, so the pagination features could be very useful. **Command** .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/checkins/?instrument=[UUID] **Response** Keep in mind that the returned data structure for searches include pagination and a *results* list. .. NOTE:: The following example has been truncated. .. code-block:: json :linenos: { "count": 17324, "next": "https://sandbox.airphoton.io/v1/checkins/?instrument=51e38515-3fb6-4f00-838b-7fea3cadc42f&limit=100&offset=100", "previous": null, "results": [ { "url": "https://sandbox.airphoton.io/v1/checkins/a7185f92-c016-430f-ae65-006c0cfa118e/", "created_time": "2020-11-24T17:01:48.261776Z", "instrument": "https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/", "control": null }, { "url": "https://sandbox.airphoton.io/v1/checkins/5e1e1e07-4720-48a8-9ee1-df57b6cf50d8/", "created_time": "2020-11-24T17:01:43.209274Z", "instrument": "https://sandbox.airphoton.io/v1/instruments/51e38515-3fb6-4f00-838b-7fea3cadc42f/", "control": null } ] } .. _data-functionality: ``data`` Functionality ---------------------- This is an object representing a file which is often instrument data uploaded remotely. It is also a place to upload scripts to be downloaded to the instruments. .. IMPORTANT:: The ``/data`` endpoint is not in production yet. .. sidebar:: ENDPOINTS | **GET** ``/v1/data/`` | **POST** ``/v1/data/`` | **GET** ``/v1/data/?:query`` **Attributes** :url: | the full URL representing the data *:uuid* :instrument: | ``string`` | URL for instrument assigned to data :control: | ``string`` or ``null`` | optional, URL for associated control resulting in data :name: | ``string`` | a common name for end-user usage :info: | ``json object`` | a json object for end-user usage :datafile: | ``string`` | partial URL to data file Example: Listing Data ~~~~~~~~~~~~~~~~~~~~~ This example retrieves a list of data for all instruments assigned to your groups. **Command** .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/data/ **Response** .. NOTE:: The following example has been truncated. .. code-block:: json :linenos: { "count": 11, "next": null, "previous": null, "results": [ { "id": "9434dbbb-5cfe-425e-b7c0-10c62c0887db", "instrument": "https://sandbox.airphoton.io/v1/instruments/c2588574-678f-45ad-ab6d-8f5195ce5bb6/", "control": "https://sandbox.airphoton.io/v1/controls/fa62d434-838c-4aa0-b6eb-32c6487b0634/", "name": null, "info": {}, "datafile": "datafiles/IN0A0003.csv" }, { "id": "d8b3b0a2-188d-4146-bd0a-f28ce4ac8470", "instrument": "https://sandbox.airphoton.io/v1/instruments/03f91ea5-065b-42c5-8b92-534b7815c423/", "control": "https://sandbox.airphoton.io/v1/controls/9d5f3edf-d8fc-43f2-b7bd-3c65211a6a87/", "name": "", "info": {}, "datafile": "datafiles/script.aps" }, { "id": "d79c3e19-0b32-420c-9600-903b2b7dc97f", "instrument": "https://sandbox.airphoton.io/v1/instruments/03f91ea5-065b-42c5-8b92-534b7815c423/", "control": "https://sandbox.airphoton.io/v1/controls/a8b83cbc-4c5c-4975-b205-c16d0d27c605/", "name": "", "info": {}, "datafile": "datafiles/script_wApIJSM.aps" }, { "id": "6129a399-6cca-4de0-8fa7-5f94acbf6afa", "instrument": "https://sandbox.airphoton.io/v1/instruments/03f91ea5-065b-42c5-8b92-534b7815c423/", "control": "https://sandbox.airphoton.io/v1/controls/ce19f85d-41ac-45c0-b1d5-cf3e6ad4a1f3/", "name": "", "info": {}, "datafile": "datafiles/INXX0084.csv" } ] } Example: Listing Data from an Instrument ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example retrieves a list of data for the specified instrument. **Command** .. code-block:: bash :linenos: curl --user [USERNAME] --request GET https://sandbox.airphoton.io/v1/data/?instrument=[UUID] **Response** Keep in mind that the returned data structure for searches include pagination and a *results* list. .. NOTE:: The following example has been truncated. .. code-block:: json :linenos: { "count": 8, "next": null, "previous": null, "results": [ { "id": "d8b3b0a2-188d-4146-bd0a-f28ce4ac8470", "instrument": "https://sandbox.airphoton.io/v1/instruments/03f91ea5-065b-42c5-8b92-534b7815c423/", "control": "https://sandbox.airphoton.io/v1/controls/9d5f3edf-d8fc-43f2-b7bd-3c65211a6a87/", "name": "", "info": {}, "datafile": "datafiles/script.aps" }, { "id": "d79c3e19-0b32-420c-9600-903b2b7dc97f", "instrument": "https://sandbox.airphoton.io/v1/instruments/03f91ea5-065b-42c5-8b92-534b7815c423/", "control": "https://sandbox.airphoton.io/v1/controls/a8b83cbc-4c5c-4975-b205-c16d0d27c605/", "name": "", "info": {}, "datafile": "datafiles/script_wApIJSM.aps" }, { "id": "6129a399-6cca-4de0-8fa7-5f94acbf6afa", "instrument": "https://sandbox.airphoton.io/v1/instruments/03f91ea5-065b-42c5-8b92-534b7815c423/", "control": "https://sandbox.airphoton.io/v1/controls/ce19f85d-41ac-45c0-b1d5-cf3e6ad4a1f3/", "name": "", "info": {}, "datafile": "datafiles/INXX0084.csv" } ] } Example: Posting a Script to Data Deployment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This example posts a script on the API server for later remotely download. **Command** .. code-block:: bash :linenos: curl --user [USERNAME] --request POST http://sandbox.airphoton.io/v1/data/ \ --form 'datafile=@"[FILEPATH]"' \ --form 'instrument="[INSTRUMENT-URL]"' **Response** .. code-block:: json :linenos: { "id": "9c411c75-4a1b-4455-a33c-18304e7ed82f", "instrument": "https://sandbox.airphoton.io/v1/instruments/03f91ea5-065b-42c5-8b92-534b7815c423/", "control": null, "name": null, "info": {}, "datafile": "datafiles/2021-02-10-EXAMPLE.aps" } .. _`backslashes`: https://stackoverflow.com/questions/3871332/how-to-tell-bash-that-the-line-continues-on-the-next-line .. _CURL: https://curl.haxx.se/ .. _FQDN: https://en.wikipedia.org/wiki/Fully_qualified_domain_name .. _HTTP: https://www.cloudflare.com/learning/ssl/why-is-http-not-secure/ .. _HTTPS: https://www.cloudflare.com/learning/ssl/why-is-http-not-secure/ .. _JSON: https://json.org/example.html .. _POSTMAN: https://www.getpostman.com/product/api-client .. _`Python script`: https://gitlab.com/airphoton/ap-io-api-scripts .. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier