Cortex Client Developer Documentation

Forms

Forms

Forms are a hypermedia control that creates new resources. Forms are generally rendered on the UI as input fields or submit buttons.

With forms, you can discover:
  • The properties required to create a resource.
  • The link to invoke the creation of a resource.
Cortex forms follow this format:
  • A type that indicates the properties that will be created in the resource.
  • Properties that define the data required to create a resource. Properties are optional, as some resources don't require data to create them.

  • Links, called action links, that invoke the creation of a resource. If an action link doesn't exist on the form, the resource cannot be created.

Form Example: Adding to cart

The items resource's addtocartform form link enables you to add the item to a cart, which means a new cart lineitem resource is created for the item. The form's type application/vnd.elasticpath.cart.lineitem indicates the form creates a cart lineitem resource:
{
  "rel": "addtocartform",  
  "type": "elasticpath.carts.line-item",
  "uri": "/carts/items/mobee/m5yxi=/form",
  "href": "http://api.elasticpath.net/cortex/carts/items/mobee/m5yxi=/form"
}
Retrieving the addtocartform form link returns the form resource, which lists the properties and actions available for the form. In this example, the form contains:
  • quantity - this property indicates the item's quantity must be specified before the item can be added to cart.
  • addtodefaultcart - this action link adds the item to the shopper's cart.
{
  "self": {
    "type": "elasticpath.carts.line-item",
    "uri": "/carts/items/mobee/m5yxi=/form",
    "href": "http://api.elasticpath.net/cortex/carts/items/mobee/m5yxi=/form",
    "max-age": 0
  },
  "quantity": 0
  "links": [
    {
      "rel": "addtodefaultcartaction",
      "uri": "/carts/mobee/default/lineitems/items/mobee/m5yxi=",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/default/lineitems/items/mobee/m5yxi="  
    }
  ]
}
To add the item to the cart, construct a POST request using the form fields as the request body and the URL defined by the action link:
POST /carts/mobee/default/lineitems/items/mobee/m5yxi=
Content-Type: application/json
{
  "quantity" : 1
}
If the action succeeds, Cortex returns status code 201 CREATED and a Location header with a reference to the newly created resource. If the action succeeds but results in modifying an existing resource rather than creating a new resource, then Cortex returns status code 200 OK and a Location header with a reference to the modified resource.
201 CREATED
Location: http://api.elasticpath.net/cortex/carts/mobee/mjt=/lineitems/gyz=  

Forms can be used with the FollowLocation request parameter to reduce the number of calls required to retrieve a newly created resource. Followlocation instructs Cortex to retrieve the resource referenced in the Location header and return it in the response body.