There are several functions for handling organism objects. To display the list of endpoints call the Swagger UI (e.g., http://localhost:5050/swagger) and select the item Organism.

The interface will show the list of functions nested under the Organism node. As you can see here, organisms can be listed, added, edited, and deleted. 

Listing organisms

To list all organisms in the database by using the UI, select the first item /api/organism/all:

Please note that each function has a description shown in the top right corner. The middle part of the panel shows the example of the output value.

The function execution is done by pressing the button "Try it out!":

To call this function from the linux prompt, run the following:

$ curl http://localhost:5050/api/organism/all
[{"Id":1,"Name":"test name","CommonName":"test common","TaxonomyNumber":999},{"Id":1753,"Name":"Allium cepa","CommonName":"onion","TaxonomyNumber":4879},...

Tip

The provided output is a machine-readable JSON text. If you plan to read it, pass the output through the jq utility. It will help format the JSON output.

When accessing this endpoint in the web browser, the JSON output can be reformatted:

This endpoint emulates the PersephoneShell's command list organism with the long listing mode showing all available details for each organism.

Another flavor of the listing command uses an individual organism name or identifier:

Provide the exact name of the organism (Allium sepa) in the name field and push "Try it out!".

To display organism by Id, use another endpoint: /api/organism/id/{id}, for example, /api/organism/id/1753.

There is also a function that displays details for organisms corresponding to a query with multiple names. The exact scientific names should be provided as a list. For the Swagger interface, there is a multi-line text field that should be filled out following a specific JSON format. Note that this method uses a POST request. If you run curl, the JSON parameter is passed as a text after the -d switch:

If you run this command under Windows, which does not recognize single quotes, it will look like this:

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d "[\"test name\",\"Allium cepa\"]" http://localhost:5050/api/organism

The double quotes in the JSON parameter should be escaped by using the back slash character.

Adding an organism

This time, we are trying to add a new organism and this step requires filling out all the relevant organism information in the JSON format. On the right you will see an example input. 

Clicking this panel will populate the config field:

Let's add a new organism Citrus sinensis. Not all values are required. We can provide just three values, others can be omitted for now. The server will auto-generate the field OrganismId trying to match TaxonomyId if possible.

There is an additional parameter called testMode. When testMode = true, the function validates all input values without adding a record to the database. This is an important pattern:

First, run the function in test mode to verify the values.

Only if validation succeeds, set testMode = false and execute the real operation.

After setting the parameters, press “Try it out!” to run the request.

The success of the test in Swagger UI can be shown by checking the status of the created task - its ID is displayed in Response Body:

The Response Body is a task identifier. It can now be used in another part of the API available under Task menu. Select the endpoint for checking the status of a task by its ID 13435116725256:

Note

Some functions take time to execute. During the execution, they can report errors. Unfortunately, after launching the task, the API cannot report the status in Return Code - the tasks can take minutes. Instead, the functions report the task ID, which can be used to see if the execution was successful.

To add the organism record, reset the flag testMode and push the button "Try it out!". To see if the new record was created, we can use the /api/organism/{name} endpoint:

Editing an organism

Let's edit a test organism record. We can find it by the search function /api/organism/search/{namePart}:

The edit function expects a JSON parameter. It specifies the Id of the record as well as the other values. The API will find the record to edit by OrganismId. So the request JSON must have OrganismId specified. We can grab one organism record from the JSON output of the search and modify the needed values, e.g., TaxonomyNumber. Let's change it to 111.

You don't have to provide all the fields if they are not being modified.

We will verify the modifications by calling /api/organism/id/1:

Deleting an organism

There are two versions of delete functions:

We can safely delete the test organism with Id = 1 as long as it has no dependent child records, such as map sets or markers. An organism can be removed only when it has no links or references to other objects in the database. The corresponding PersephoneShell command is delete orphan_organism. Deleting an organism with its dependent map sets or markers is blocked - it is too destructive.

Similar to adding organisms, the function will return TaskID in Response Body, which can be used to find the status of the operation by calling an endpoint for a specific task identified by its ID: /api/task/13436925928735.