Create & Update

Describe - get a list of mandatory and optional parameters

GET /api/<class>/describe/

This request returns a generated list of mandatory and optional parameters for record creation and updating, as well as a list of permissions needed for any action. If a specific action is not listed, it cannot be used manually (e.g. create stock, etc.).

Please note that lists of mandatory and optional parameters are generated from the inner code structure and there can be some additional rules that may not be visible here, for example, when creating a fishline you have to set either alias or genotypes, so technically there are no mandatory parameters. However, if you omit both fields, the request will fail.

If you need any help or if you find a bug (e.g. describe that is uselessly inaccurate), don't hesitate to ask for help.

Response

Example 1 - Fishline

{
  "model": {
    "class": "FishLine",
    "table": "fishline"
  },
  "create": {
    "mandatory": [],
    "optional": [
      "attachments",
      "projects",
      "species_id",
      "description",
      "workgroups",
      "suffix",
      "funding_id",
      "in_facility_since",
      "publications",
      "origin_id",
      "source_id",
      "alias",
      "responsible_user_id",
      "background_id",
      "genotypes"
    ]
  },
  "update": {
    "optional": [
      "attachments",
      "source_id",
      "alias",
      "projects",
      "species_id",
      "description",
      "in_facility_since",
      "responsible_user_id",
      "workgroups",
      "funding_id",
      "suffix",
      "background_id",
      "publications",
      "origin_id"
    ]
  },
  "permissions": {
    "create": [
      "zebrabase.fishline_modify"
    ],
    "multicreate": [
      "zebrabase.fishline_modify"
    ],
    "update": [
      "zebrabase.fishline_modify"
    ],
    "destroy": [
      "zebrabase.fishline_modify",
      "zebrabase.fishline_destroy"
    ],
    "genotype_visibility": [
      "zebrabase.fishline_modify",
      "zebrabase.fishline_genotype_visibility"
    ],
    "burden": [
      "zebrabase.fishline_modify",
      "zebrabase.fishline_set_burden"
    ]
  }
}

Example 2 - Project

{
  "model": {
    "class": "Project",
    "table": "project"
  },
  "create": {
    "mandatory": [
      "name",
      "leader_id",
      "code"
    ],
    "optional": [
      "deputy_id",
      "attachments",
      "procedures",
      "leader_id",
      "code",
      "users",
      "description",
      "fish_limit",
      "expiration",
      "start",
      "name"
    ]
  },
  "update": {
    "optional": [
      "deputy_id",
      "attachments",
      "procedures",
      "leader_id",
      "code",
      "users",
      "description",
      "fish_limit",
      "expiration",
      "start",
      "name"
    ]
  },
  "permissions": {
    "create": [
      "zebrabase.project_modify"
    ],
    "multicreate": [
      "zebrabase.project_modify"
    ],
    "update": [
      "zebrabase.project_modify"
    ],
    "destroy": [
      "zebrabase.db_admin"
    ]
  }
}

Create

POST /api/<class>/ + DATA

Creation returns the detail of the created object if successful.

The mandatory and optional data for each class are listed in the response for /api/<class>/describe/. If not satisfied, the response will be an error message stating which parameters are bad or missing.

Example

One missing mandatory parameter and one excessive parameter: POST /api/fishline/ DATA: {"responsible_user_id": 1000, "something": "nothing"}

Curl: curl -d '{"responsible_user_id": 1000, "something": "nothing"}' -X POST /api/<class>/

{
  "detail": "At least one of these params must be specified: 'alias', 'genotypes'",
  "info": {},
  "status_code": 400,
  "exception_class": "MandatoryParamMissingException",
  "messages": null
}

Let's add the mandatory parameter: POST /api/fishline/ DATA: {"alias": "test", "responsible_user_id": 1000, "something": "nothing"}

{
  "detail": "These parameters are not necessary: {'something'}",
  "info": {},
  "status_code": 400,
  "exception_class": "UnnecessaryParamException",
  "messages": null
}

Non-existent value: POST /api/fishline/ DATA: {"alias": "test", "responsible_user_id": 1009}

{
  "detail": "Request lead to database integrity error: insert or update on table \"fishline\" violates foreign key constraint \"fishline_responsible_user_id_fkey\"\nDETAIL:  Key (responsible_user_id)=(1009) is not present in table \"auth_user\".\n.",
  "info": {},
  "status_code": 400,
  "exception_class": "ZBIntegrityError",
  "messages": null
}

Correct command: POST /api/fishline/ DATA: {"alias": "test", "responsible_user_id": 1000}

{
  "id": 428,
  "name": "test",
  "name_gen": null,
  "name_base": null,
  "alias": "test",
  "in_facility_since": null,
  "description": null,
  "background_id": null,
  "background_name": null,
  "origin_id": null,
  "origin_name": null,
  "source_id": null,
  "source_name": null,
  "responsible_user_id": 1000,
  "suffix": "",
  "species_id": null,
  "species_name": null,
  "active": true,
  "first_burden_check": null,
  "second_burden_check": null,
  "second_burden_check_after": null,
  "funding_id": null,
  "funding_name": null,
  "current_author_id": 984,
  "updated": "2024-04-11T12:36:13.824891Z",
  "last_burden_confirm": null
}

Multicreate

POST /api/<class>/multicreate/ + DATA

This feature allows the creation of multiple instances with one request. The main difference between this solution and just repeating the create request is transaction safety: if any creation from multicreate fails, the whole batch is rolled back.

Data has to be a list of data for each instance, e.g.: POST /api/affectedgene/multicreate/ DATA: [{"name": "A"}, {"name": "B"}, {"name": "C"}]

The response is a list of new objects:

[
  {
    "id": 4,
    "name": "A",
    "active": true
  },
  {
    "id": 5,
    "name": "B",
    "active": true
  },
  {
    "id": 6,
    "name": "C",
    "active": true
  }
]

Update

PUT /api/<class>/<object id>/ + DATA

Update returns the detail of the created object if successful

Parameters available for the update are listed in /api/<class>/describe/.