Adding a new Item

3. Adding a new Item

Do a POST request to /v1/items, ora a PUT to /v1/items/CODE if you want to manually assign a code. If some items don't have a code, the server will try to generate one for each item.

You must use the session cookie to authenticate this request.
The request body should look like this:

{
  "parent": "SomeLocation",
  "features": {
    "brand": "Dill",
    "model": "XP-S92",
    "type": "case"
  },
  "contents": []
}

It's also possible to add a tree of items. In that case, if you want to specify a code for inner items, you should use the "code" parameter.
The "code" parameter is not allowed for outer items.

{
  "parent": "SomeLocation",
  "features": {
    "model": "XP-S92",
    "brand": "Dill",
    "type": "case"
  },
  "contents": [
    {
      "features": {
        "type": "motherboard",
        "brand": "Dell",
        "model": "F00-B4R"
      },
      "contents": [
        {
          "features": {
            "type": "cpu",
            "brand": "Intel",
            "model": "Core 3 Trio E3800",
            "frequency-hertz": "2800000000"
          },
          "contents": []
        }
      ]
    },
    {
      "code": "ASD",
      "features": {
        "type": "psu",
        "brand": "Gamma Electronics",
        "model": "ASD-400W"
      },
      "contents": []
    }
  ]
}

Responses contain the item code as the only data:

{"status":"success", "data":"PC42"}

or you may use the ?loopback parameter to request a copy of the entire item, e.g. do a POST /v1/items?loopback ora a PUT /v1/items/CODE?loopback.

In any case, the response contains a Location: header with the URL of the newly added item, e.g.:

Location: /v1/items/PC42

Response codes:
201 - Item created
400 - Bad request (malformed JSON, validation failed, location does not exist, etc...)
403 - The user is not authenticated or session has expired
404 - Item code contains invalid characters. Yes this is a bug and will be fixed someday

3.1 Validation and "fixup"

All items go through a two-step validation process, that takes into account their features and their location:

• Fixup: try to move misplaced items to their correct location
• Validation: check that no impossible placements are still there, accept or reject the entire request accordingly

For instance, fixup moves RAM modules from a case to the motherboard contained inside it. If the motherboard could not be found or the fixup could not be applied, the request still goes through to the next phase.

Validation checks that RAM and motherboards have the same socket, and does the same for CPUs and motherboards, and prevents impossible placements like a CPU inside a HDD, and the like. If any validation step fails, the entire request is rejected.

This is done both for newly added items, and for "move" operations.
The src/ItemLocationValidator.php file contains the code that does all these checks.

Both validation and fixup can be disabled on a per-request basis, with a parameter which will not be named since you shouldn't use it: if you really (and desperately) need it, check APIv1/Controller.php.