Creating, Modifying, and Deleting Data

Liferay's headless APIs provide powerful capabilities for scalable resource management. Standard REST endpoints and GraphQL mutations enable you to select optimal data manipulation approaches. This article explores how to create, update, and delete data with Liferay's headless APIs.

Manipulating Data with REST

REST APIs in Liferay provide the following HTTP methods for data manipulation:

Method	Purpose
POST	Create a resource.
PUT	Replace an existing resource entirely.
PATCH	Update specific fields of an existing resource.
DELETE	Remove a resource.

While PUT and PATCH both update existing data, they approach modification differently:

PUT: Updates all specified fields and resets any fields not included in the payload.
PATCH: Modifies only specified fields and avoids unintended data resets.

See Consuming REST Services for more information and examples of modifying data with REST APIs.

NOTE
Available HTTP methods vary by endpoint. Refer to the API Explorer at http[s]://[server]:[port]/o/api for endpoint details.

Modifying Clarity's Object Entries

Clarity plans to leverage headless APIs to create, update, and delete object entries across their environments. Within their ticketing application, the Ticket object exposes a set of REST endpoints for managing tickets via the /o/c/tickets/ endpoint.

For example, Clarity can use the POST endpoint to enable team members to create object entries via their custom dashboard. A sample POST request might look like this:

POST /o/c/tickets/
{
  "subject": "System Outage",
  "description": "Critical system outage affecting customer operations.",
  "priority": {
    "key": "critical"
  },
  "region": {
    "key": "lATAM"
  },
  "ticketStatus": {
    "key": "open"
  },
  "type": {
    "key": "other"
  },
  "r_userToTicket_userERC": "M2H8_SUPPORT_SAM"
}

Clarity can also use PUT or PATCH to update existing ticket entries via their custom UI. These requests would resemble the POST request, though they'd specify a ticket to modify (e.g., ticketId) and may only include a subset of object fields. For example, they could use a PATCH request to update an entry's status and resolution without changing any of the other field values.

PATCH /o/c/tickets/{ticketId}
{
  "ticketStatus": {
    "key": "closed"
  },
  "resolution": "Issue resolved by system patch."
}

Alternatively, if this request used the PUT method, it would update the ticketStatus and resolution values while reset all other field values to null. By using a streamlined PATCH, Clarity can update select fields (e.g., priority, status) without needing to include all other field values in the request. This simplifies payloads while avoiding data loss.

To manage tickets, Clarity can also leverage the DELETE method in their UI, enabling support team members to delete unwanted tickets from the system. These calls only need to specify which ticket to remove and require no additional payload.

NOTE

While these examples use resource IDs, many REST applications include endpoints that identify assets using External Reference Codes (ERCs). Clarity's Tickets object includes endpoints for updating and deleting entries by ERC:

/o/c/tickets/by-external-reference-code/{externalReferenceCode}

Clarity's Object Action PUT Endpoints

In addition to updating existing resources, you can also use dedicated endpoints for triggering standalone object actions. When you define a standalone trigger, Liferay generates two API endpoints for executing the action. You can call these endpoints programmatically or manually, independent of object entry events.

For example, Clarity could provide a button in their custom Ticketing UI that calls the AssignTicketToMe action using this endpoint:

PUT /o/c/tickets/by-external-reference-code/{externalReferenceCode}/object-actions/AssignTicketToMe

These endpoints empower developers to trigger custom business logic via APIs.

Manipulating Data with GraphQL

GraphQL provides a flexible alternative for manipulating data. For example, Clarity's developers could execute this call to create a ticket with values identical to the above POST example:

mutation {
  c {
    createTicket (Ticket:
      {subject: "System Outage",
        priority: {key: "critical"},
        region: {key: "lATAM"},
        ticketStatus: {key: "open"},
        type: {key: "other"}
      }
    ) {
      id
      subject
      description
      priority {
        key
      }
      region {
        key
      }
      ticketStatus {
        key
      }
      type {
        key
      }
    }
  }
}

An identical mutation leveraging the updateTicket method instead of createTicket would modify this created ticket to include new field values. See Consuming GraphQL APIs for more information about interacting with data through GraphQL.

NOTE
GraphQL mutations for objects APIs have notable limitations. Unavailable actions include updating objects using ERC, invoking object actions, accessing relationship APIs, and updating only select fields with PATCH methods.

Conclusion

Liferay's headless APIs provide a robust framework for data manipulation through standard HTTP methods. Object actions further extend API capabilities by enabling custom business logic execution. In addition to comprehensive REST data manipulation tools, GraphQL offers a flexible alternative. Understanding the distinctions between methods enables efficient and controlled data management.

Next, you'll use these methods to create, modify and delete ticket entries.