Differential D14798 Diff 35779 src/docs/user/userguide/conduit_edit.diviner

Changeset View

Standalone View

src/docs/user/userguide/conduit_edit.diviner

This file was added.

				@title Conduit API: Using Edit Endpoints
				@group conduit

				Describes how to use edit endpoints to create and update objects.

				Overview
				========

				Many applications provide `edit` endpoints, which are the primary way to
				create and update objects (like tasks) using the API.

				To create or edit an object, you'll build a list of //transactions// and pass
				them to the endpoint. Each transaction applies a change to a field or property
				on the object.

				For example, a transaction might change the title of an object or add
				subscribers.

				When creating an object, transactions will be applied to an empty object. When
				editing an object, transactions will be applied to an existing object.

				The best reference for a particular `edit` endpoint is the Conduit API console.
				For example, you can find the console page for `maniphest.edit` by navigating
				to {nav Conduit > maniphest.edit} in the web UI. This page contains detailed
				information about the endpoint and how it can be used.

				Creating Objects
				================

				To create objects, pass a list of transactions but leave `objectIdentfier`
				blank. This tells the endpoint that you want to create a new, empty object and
				then apply the transactions to it.


				Editing Objects
				===============

				To edit objects, pass a list of transactions and use `objectIdentifier` to
				specify which object to apply them to. You can normally pass an ID or PHID,
				and many applicaitons also allow you to pass a monogram (for example, you can
				edit a task by passing `T123`).


				Building Transactions
				=====================

				When creating or editing objects, you'll build a list of transactions to
				apply. This transaction list will look something like this:

				```lang=json, name="Example Transaction List"
				[
				{
				"type": "title",
				"value": "Assemble in the barnyard"
				},
				{
				"type": "description",
				"value": "All animals should assemble in the barnyard promptly."
				},
				{
				"type": "subscribers.add",
				"value": ["dog", "cat", "mouse"]
				}
				]
				```

				Applied to an empty object (say, a task), these transactions would create a new
				task with the specified title, description and subscribers.

				Applied to an existing object, they would retitle the task, change its
				description, and add new subscribers.

				The particular transactions available on each object are documented on the
				Conduit API console page for that object.


				Return Type
				===========

				WARNING: The structure of the return value from these methods is likely to
				change as ApplicationEditor evolves.

				Return values look something like this for now:

				```lang=json, name=Example Return Value
				{
				"object": {
				"phid": "PHID-XXXX-1111"
				},
				"transactions": [
				{
				"phid": "PHID-YYYY-1111",
				},
				{
				"phid": "PHID-YYYY-2222",
				}
				]
				}
				```

				The `object` key contains information about the object which was created or
				edited.

				The `transactions` key contains information about the transactions which were
				actually applied. For many reasons, the transactions which actually apply may
				be greater or fewer in number than the transactions you provided, or may differ
				in their nature in other ways.


				Next Steps
				==========

				Continue by:

				- returning to the @{article:Conduit API Overview}.