List Items Update API

Route

PUT

Purpose

Parameters

token string 100 required

Authentication token for either an application or session.

application string 200

Slug of application being requested. This is used to determine the role being used to make the request and therefore evaluate if the requester has the correct permissions.

Possible values

planoauth
planoorder
planox2

session_view string 300

View of session object you would like returned.

id integer 400 required

Id of record being requested.

view string 500

The view attribute controls what data is returned about the requested record.

Possible values

default

name string 1200

Readable name of the list_ltem. This is generally the readable version of the list_item slug.

value string 1300

Certain collections of list items require having a value for each list item. This attribute is used to hold that data.

description string 1400

In addition to a value, some collections of list items need a description. You can think of this attribute as additional elaboration of the list item if needed. Limit: 1000

notes string 1500

The notes attribute is helpful if any internal contexted is needed for a list item. For example, if a list item's name is changed but the slug isn't for programitic reasons, a note can be added here for future context.

active boolean 1600

The active attribute controls whether a list item in a collection is active. In most cases, this means that inactive list items don't show up in lists.

Possible values

true
false

default boolean 1700

If default is passed as true, this list item will be marked as the sole default in the collection. If there was already a default list item in the collection, that list item will loose it's title as default.

Possible values

true
false

external_id string 1800

In some cases, list items in a collection have an external_id associated to the item. For example, our collection of glip_teams have external Glip ids. https://planocore.planomatic.com/documentation/list_items/glip_team

item_type model 1900

In some cases, list items in a collection have records that they are associated to via polymorphic association. These associations can be made by specifying the model and id of the assoication. The item_type accepts a model class name which should be in CamelCase, e.g., Designation, OrderRequest. An example of a collection using this can be found in the client_designation_discovery collection. https://planocore.planomatic.com/documentation/list_items/client_designation_discovery

item_id integer 2000

This attribute is tied to the item_type param. When an item_type is passed the item_id is needed specifiy which record the list item is associated to. This can be seen in the assoication in https://planocore.planomatic.com/documentation/list_items/client_designation_discovery.

related_type model 2100

If an additional polymorphic association is needed in a list_item collection, you can used the related_type to specifiy the model of the second association in CamelCase, e.g., Designation, OrderRequest.

related_id integer 2200

This attribute is tied to the related_type param. When an related_type is passed the related_id is needed specifiy which record the list item is associated to.

Request Body Example: application/json

          {"token": "Sw543vdfgswWg98", "application": "planoauth", "session_view": null, "id": 2303, "view": "default", "name": "New list item", "value": "Value of list item", "description": "Description of list item", "notes": "Notes", "active": true, "default": true, "external_id": "123abc", "item_type": "Designation", "item_id": 2, "related_type": "Vendor", "related_id": 1}

Responses

action-successful 200

This status indicates that the request was successful. If the request returns data, it can be found in the data key.

  {"code": 200, "data": {}, "status": "action-successful", "message": "..."}

invalid-token 401

This status is returned when the authentication token passed is invalid.

  {"code": 401, "status": "invalid-token", "message": "..."}

session-expired 401

This status is returned a session is older than seven days or hasn't been used in 72 hours. The user will need to reauthenticate. We allow our users to save a remember_me preference which will make there sessions last indefinitely.

  {"code": 401, "status": "session-expired", "message": "..."}

client-required 401

This status is returned when the user makeing the request doesn't have a client, employee or liaison record. This means that they don't have any roles or permissions. Because we only allow our clients to register as a client, the user should be redirected to the PlanoAuth clients registration page where they can use the `/api/v1/users/client_register` API to register as a client. Eventhough the request will not be successful, this status will still return a `session` object because a session token is needed to register as a user.

  {"code": 401, "status": "client-required", "message": "...", "session": {}}

missing-param 400

This status is returned when a required param was not passed with the request.

  {"code": 400, "status": "missing-param", "message": "...", "missing_param": "email"}

invalid-param 400

This status is returned when a param was invalid when passed. For example, passing an id that doesn't exist or passing an invalid email address.

  {"code": 400, "status": "invalid-param", "message": "...", "invalid_param": "email"}

application-crash 500

This status is returned when there is an internal server error. Please try again later.

  {"code": 500, "errors": "...", "status": "application-crash", "message": "..."}

mandrill-email-failed 500

This status is returned when there was an issue using Mandrill to send an email. Any time this response is returned, there will be a notification in the production notifications tab so the dev team will be away of the failure. These errors will most likely correlate with a data issue and will need to be invesigated.

  {"code": 500, "errors": "...", "status": "mandrill-email-failed", "message": "..."}

invalid-content-type 400

This status is returned if the request was made with the incorrect content-type so the request params could not be read. For more infromation on content-type, please refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type.

  {"code": 400, "status": "invalid-content-type", "message": "...", "content_type_passed": "application/json", "content_type_required": "text/plain"}

route-non-existent 500

Response returned when HTTP route does not exist.

  {"code": 500, "status": "route-non-existent", "message": "..."}

Uncommon Responses

The responses below are not very common.

no-params-decoded Uncommon

This status is returned the request body was decoded, but no params where found.

  {"code": 400, "status": "no-params-decoded", "message": "..."}

invalid-encoded-params Uncommon

This status is returned when the request body could not be decoded properly. This generally means that you are requesting a sensative_params API and your request body was not base64 encoded.

  {"code": 400, "errors": "...", "status": "invalid-encoded-params"}

route-not-found Uncommon

This status is returned when the route record being requested hasn't been deployed yet.

  {"code": 404, "path": "...", "status": "route-not-found", "message": "...", "http_method": "..."}

identify-request-error Uncommon

This status is returned when there is an internal server error before the route could be identified. Please try again later.

  {"code": 500, "errors": "...", "status": "identify-request-error", "message": "..."}

service-not-found Uncommon

This status is returned when the route's API service record being requested hasn't been deployed yet.

  {"code": 404, "status": "service-not-found", "message": "...", "route_id": "...", "api_service_key": "..."}