Apply Edits (Feature Service/Layer)
- URL:https://<featurelayer-url>/applyEdits(POST only)
- Required Capability:Create, Update, Delete. Create is required to add features, Update is required to update features, and Delete is required to delete features.
- Version Introduced:10.0
Description
The applyEdits operation adds, updates, and deletes features to the associated feature layer or table in a single call and returns the results of the edits that are grouped by the type of edit (addResults, updateResults, and deleteResults). Each grouping contains an array of edit result objects that identify a single feature and indicates whether the edits were successful. If the edits were unsuccessful, the edit result object includes an error code and error description. This operation is performed on a feature service layer resource.
Note:Hosted feature services support adding and updating BLOB column values in Base64.
Note:Any geometry edits made to the layer are validated with OGC standards.
Starting at ArcGIS Enterprise 10.6, services can be published from enterprise geodatabase layers that have attribute rules. Attribute rules are applied to the back-end datasets and take effect when edits are applied. Types of attribute rules include calculation rules that automatically apply a calculated value to a field and constraint rules that cause an edit to return an error if the constraint is violated. For an example, see the constraint rule violation JSON response below.
New at 11.1
- This operation now includes the editsUploadId parameter. Support for the new parameter is indicated when the layer-level supportsApplyEditsbyUploadID property, under advancedEditingCapabilities, is set to true.Note:
The layer-level supportedApplyEditsUploadFormats properties, under advancedEditingCapabilities, indicate which formats can be used for the edits in the uploaded file.
- For non-hosted feature services referencing an enterprise geodatabase, the async parameter now uses a geoprocessing service, which allows for longer running operations.
- For hosted feature services, a field's default value is now applied when a row is added with no provided value when using either this operation or Append.Note:
This enhancement matches behavior already present for ArcGIS Online hosted feature services and ArcGIS Enterprise non-hosted feature services.
New at 11.0
The following are new at 11.0:
- ArcGIS Enterprise hosted feature services now support the async parameter.
- A new parameter, returnEditResults, was introduced at this release. When set to false, applyEdits only returns a response of the following form:The returnEditResults parameter can be set to false only when rollbackOnFailure is set to true. Support for this new parameter is indicated by a feature service having the layer-level supportsReturnedEditResults property, under advancedEditingCapabilities, set to true.
{"success": <true|false>}
New at 10.9.1
The layer-level applyEdits operation for hosted feature services in ArcGIS Online, and non-hosted feature services in ArcGIS Enterprise, includes an option to process requests asynchronously. This option is ideal for longer-running edit operations that may time out otherwise. The async parameter can be used if the layer resource has the supportsAsyncApplyEdits layer property set to true (under advancedEditingCapabilities).
New at 10.9
A new parameter, timeReferenceUnknownClient, has been added at 10.9. Setting timeReferenceUnknownClient to true indicates that the client is capable of working with date field data values that are not in UTC. For more information about this parameter, see the Request parameters table below.
Request parameters
|
Parameter |
Details |
|---|---|
| adds
(Optional. At least one of the following parameters must be included in the request: adds, updates, or deletes) | The array of features to be added. The structure of each feature in the array is the same as the structure of the JSON feature object returned by the ArcGIS REST API. Features to be added to a feature layer should include the geometry. Records to be added to a table should not include geometry. If useGlobalIds is true, the features are added while preserving their globalIds values. If useGlobalIds is false or not specified, the globalIds values submitted with the features are ignored and the service assigns new globalIds values to the new features. Syntax Example |
| updates
(Optional. At least one of the following parameters must be included in the request: adds, updates, or deletes) | The array of features to be updated. The structure of each feature in the array is the same as the structure of the JSON feature object returned by the ArcGIS REST API and includes a globalId value. Records to be added to a table should not include geometry. If useGlobalIds is false or not specified, the attributes property of the feature should include the object ID of the feature along with the other attributes (the globalId value of the feature is not required). If useGlobalIds is true, the globalId value is used to identify the feature when applying the update (the object ID of the feature is not required). Syntax Example 1: Example 2, when useGlobalIds is true: |
| deletes
(Optional. At least one of the following parameters must be included in the request: adds, updates, or deletes) | The object IDs of the features or records to be deleted. If useGlobalIds is false or not specified, the objectIds values of the features to be deleted must be provided. If useGlobalIds is true, the globalIds values of the features to be deleted must be provided. Syntax Example |
| gdbVersion | The geodatabase version to apply the edits. This parameter applies only if the isDataVersioned layer-level property is true. If gdbVersion is not specified, edits are made to the published map's version. Syntax Example |
| returnEditMoment (Optional) | Introduced at 10.5. This is only applicable for ArcGIS Server services. Specifies whether the response will report the time that edits were applied. If set to true, the server will return the time in the response's editMoment key. The default value is false. Values: true | false |
| rollbackOnFailure (Optional) | Specifies whether the edits will be applied only if all submitted edits succeed. If false, the server will apply the edits that succeed, even if some of the submitted edits fail. If true, only the edits that succeed will be applied. The default value is true. Note:Not all data supports this parameter. To verify support for this parameter, query the supportsRollbackonFailureParameter layer-level property. If the supportsRollbackonFailureParameter layer-level property is false, rollbackOnFailure will be treated as if it were set to true, regardless of the input. If the supportsRollbackonFailureParameter layer-level property is true, the value set for rollbackOnFailure will be honored for edit operations. The supportsRollbackOnFailureParameter property will always be true if the published data is nonversioned, or nonversioned with archiving enabled with no composite relationships or attachments. Values: true|false |
| useGlobalIds (Optional) | When set to true, the features and attachments in the adds, updates, deletes, and attachments parameters are identified by their gloablIds value rather than their objectId or attachmentId value. The service adds the new features and attachments while preserving the globalId value submitted in the payload. If the globalId value of a feature or attachment conflicts with an existing feature or attachment, the addition of that feature or attachment fails. Other additions, updates, or deletions are attempted if rollbackOnFailure is false. If rollbackOnFailure is true, the entire operation fails and rolls back on any failure, including a globalId conflict. The default value is false. Note:This parameter requires the layer's supportsApplyEditsWithGlobalIds property to be true. Values: true | false |
| attachments (Optional) | This parameter adds, updates, or deletes attachments. It applies only when the useGlobalIds parameter is set to true. When set to adds, the globalIds values of the attachments provided by the client are preserved. When useGlobalIds is true, the updates and deletes options are identified by each feature or attachment globalId value, rather than their objectId or attachmentId value. This parameter requires the layer's supportsApplyEditsWithGlobalIds property to be true. Attachments to be added or updated can use either pre-uploaded data or base 64 encoded data. Note: Attachments can be edited using the feature resource regardless of the supportsApplyEditsWithGlobalIds property value. Syntax: Example: |
| assetMaps (Optional) | Introduced at ArcGIS Enterprise 11.1. Specifies an array of adds and updates (similar to attachments) for feature layer assetsassets associated with a 3D Object Feature Layer. For more information, see the Apply Edits with Asset Maps section below. |
| trueCurveClient (Optional) | Indicates to the server whether the client is true curve capable. When set to true, true curve geometries will be downloaded and geometries containing true curves will be used by the map service without densifying it. When set to false, the client is not true curves capable. The default value is false. Values: true | false |
| sessionID (Optional) | Introduced at 10.6. The sessionID is a GUID value that clients establish at the beginning and use throughout the edit session. The sessonID parameter ensures isolation during the edit session. The sessionID parameter is set by a client during long transaction editing on a branch version. Syntax Example |
| usePreviousEditMoment (Optional) | Introduced at 10.6. The usePreviousEditMoment parameter is used to apply the edits with the same edit moment as the previous set of edits. This allows an editor to apply a single block of edits partially, complete another task, and complete the block of edits. This parameter is set by a client during long transaction editing on a branch version. When set to true, the edits are applied with the same edit moment as the previous set of edits. When set to false or not set (the default), the edits are applied with a new edit moment. Values: true | false |
| datumTransformation (Optional) | Introduced at 10.8. This parameter applies a datum transformation while projecting input geometries from their spatial reference to the layer's source spatial reference. When specifying transformations, you need to think about which datum transformation is best for this projection. For a list of valid datum transformation ID values and well-known text strings, see Using spatial references. For more information on datum transformations, see the transformation parameter in the Project operation. Syntax Example |
| timeReferenceUnknownClient | Setting timeReferenceUnknownClient to true indicates that the client is capable of working with data values that are not in UTC. If its not set to true, and the service layer's datesInUnknownTimeZone property is set to true, an error is returned. The default is false It's possible to define a service's time zone of date fields as unknown. Setting the time zone to unknown means that date values will be returned as is from the database, rather than as date values in UTC. Non-hosted feature services can be set to use an unknown time zone using ArcGIS Server Manager. Setting the time zones to unknown also sets the datesInUnknownTimeZone layer property to true. Currently, hosted feature services do not support this setting. This setting does not apply to editor tracking date fields, which are stored and returned in UTC even when the time zone is set to unknown. Most clients released prior to ArcGIS Enterprise 10.9 will not be able to work with feature services that have an unknown time setting. The timeReferenceUnknownClient parameter prevents these clients from working with the service to avoid problems. Setting this parameter to true indicates that the client is capable of working with unknown date values that are not in UTC. Note:ArcGIS Pro 2.7 or later supports these feature services. Value: true | false |
| async | New at 10.9.1. The async parameter can be used if the layer resource has the supportsAsyncApplyEdits property set to true (found under advancedEditingCapabilities). If true, the request is processed as an asynchronous job, and a URL is returned that a client can visit to check the status of the job (statusUrl). The default value is false. For more information, see the topic on asynchronous usage for more information. The status and resultUrl properties are returned when checking the status of a job. However, the other asynchronous properties may not be returned. Once the status is COMPLETED, a resultUrl is provided that returns responses matching the JSON response example below. Async applyEdits is intended for longer-running edit operations that may time out in synchronous mode while the client is waiting for a response. For larger and longer-running processes, it is recommended that you use other operations, such as append, instead of applyEdits. For ArcGIS Enterprise non-hosted feature services, the async process is subject to the feature service time-out settings. For example, if the maximum time a client can use a service is 10 minutes, the async process will run up to 10 minutes. The number of instances configured per machine will also be shared by both synchronous and asynchronous calls. Values: true | false |
| returnEditResults (Optional) | Introduced at 11.0. Determines whether the request returns results per edit or a standard success response. When set to false, the request returns only a response of the following form: The returnEditResults parameter can only be set to false when rollbackOnFailure is set to true. When returnEditResults is set to true, the request returns results per edit. The default value is true. Note:This parameter is only supported for feature service layers that have the supportsReturnEditResults layer-level property, under advancedEditingCapabilities, set to true. Values: true | false |
| editsUploadId (Optional) | Introduced at ArcGIS Enterprise 11.1 for hosted and non-hosted feature services. This parameter references an upload ID from an uploaded file containing service edits. This parameter provides the option to pre-upload edits to the ArcGIS Server and reference them through this parameter, rather than provide edits in-line with the edits parameter. The input for editsUploadId is the ID returned after performing the upload operation. If both edit and editsUploadId are included in a request, this parameter will take precedence. Note:Support is for this parameter is indicated when the service-level supportsApplyEditsbyUploadID property, under advancedEditingCapabilities, is true. Supported formats for the file containing service edits are listed in the service-level supportedApplyEditsUploadIDFormats property, under advancedEditingCapabilities. For example, when JSON is listed as a supported upload format, the content of the file can be in JSON format. Syntax example Example Example upload file content |
| f |
The response format. The default format is html. Values: html | json | pjson |
Example usage
The following is a sample request URL used to access the applyEdits endpoint:
https://machine.domain.com/webadaptor/rest/services/SanFrancisco/311Incidents/FeatureServer/0/applyEdits
Apply Edits for 3D Object Feature Layer
The layer level applyEdits operation has a parameter called assetMaps which is used to perform adds and updates to a 3D Object Feature Layer.
Both 3D Feature Layer aware clients and 3D Feature Layer unaware clients or applications can access the applyEdits operation. Applications or clients that are 3D Feature Layer aware will send the assetMaps field and omit geometry. An application or client that is not 3D Feature Layer aware will send a multipatch feature where the geometry contains all the information, and will not send the assetMaps parameter. The layer supports both kinds of clients.
Example adds request with assetMaps:
adds=[
{
"attributes": {
"OWNER": "Joe Smith",
"VALUE": 94820.37,
"APPROVED": true,
"LASTUPDATE": 1227663551096,
"GlobalID": "{064185b3-d827-fa42-a9bb-aff1ccb9b6a1}"
}
}
]
assetMaps={
"adds":[
{
"globalId": "{c9e887e9-c8bd-4014-be62-03e5b0f7b25f}"
"parentGlobalId": "{064185b3-d827-fa42-a9bb-aff1ccb9b6a1}"
"assetName": "geometry.glb",
"assetHash": "6486ee53c8faba18045ef29d382f1c8227bde3a25d37f7a62fe0d2259a3a14dd",
"flags": ["PROJECT_VERTICES"]
}
]
}
The updates array will also have a corresponding entry in assetMaps for each feature, similar to those the adds array has. As with the existing applyEdits, attributes and assetMaps are each optional and will result in a partial update of the feature (i.e., only attributes, only shape). The existing geometry and the new assetMaps are mutually exclusive.
Response Syntax:
{
"addResults": [<editResult1>}, <editResult2>],
"updateResults": [<editResult1>}, <editResult2>],
"deleteResults": [<editResult1>}, <editResult2>],
"attachments": {
"addResults": [<attachmentEditResult1>, <attachmentEditResult2>],
"updateResults": [<attachmentEditResult1>, <attachmentEditResult2>],
"deleteResults": [<attachmentEditResult1>, <attachmentEditResult2>]
}
"assetMaps": {
"addResults": [<assetMapsEditResult1>, <assetMapsEditResult2>],
"updateResults": [<assetMapsResult1>, <assetMapsEditResult2>]
}
}
Example response:
{
"addResults": [
{
"objectId": 618,
"globalId": "{74100804-E229-49b8-8CDC-9B5D3EF03EDA}",
"success": true
},
{
"objectId": 619,
"globalId": "{39B856DC-AFE4-4c02-B433-A9361ACD91CF}",
"success": true
}
],
"updateResults": [
{
"objectId": 50,
"globalId": "{9537AFCE-BF6B-4931-93E8-403E12D76916}",
"success": false,
"error": {
"code": 1019,
"description": "Violated attribute constraint rule. [Error No: -1, ]"
}
}
],
"deleteResults": [
{
"objectId": 25,
"globalId": "{1A9F8368-F9BB-428B-BB03-F45724362DB5}",
"success": true
},
{
"objectId": 26,
"globalId": "{6CE34136-EC3A-40D7-80BF-E1D9BE33812A}",
"success": true
}
],
"assetMaps": {
"addResults": [
{
"GlobalID": "{c9e887e9-c8bd-4014-be62-03e5b0f7b25f}",
"success": true
},
{
"GlobalId": "{62ed3f5e-467a-444d-ad25-ed7e559ef14b}",
"success": true
}
],
"updateResults": [
{
"GlobalId": "{9db72076-e109-467e-94c7-3d5a3a4ef9ef}",
"success": true
}
]
}
}
Example 1
The following is a sample POST request that demonstrates adding an array of features using the applyEdits operation on a feature service layer resource, formatted for readability:
POST /webadaptor/rest/services/SanFrancisco/311Incidents/FeatureServer/0/applyEdits HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
adds=[
{
"attributes": {
"req_id": "508389",
"req_type": "Graffiti Complaint - Public Property",
"req_date": "09\/19\/2009",
"req_time": "18:44",
"address": "11TH ST and HARRISON ST",
"x_coord": "6008925.0",
"y_coord": "2108713.8",
"district": "6",
"status": 1
},
"geometry": {
"x": -122.41247978999991,
"y": 37.770630098000083
}
},
{
"attributes": {
"req_id": "508395",
"req_type": "Graffiti Complaint - Public Property",
"req_date": "09\/19\/2009",
"req_time": "19:01",
"address": "13TH ST and MANCHESTER ST",
"x_coord": "6008929.0",
"y_coord": "2108713.9",
"district": "6",
"status": 1
},
"geometry": {
"x": -121.42248867898987,
"y": 38.790630098000452
}
}
]&updates=&deletes=&gdbVersion=&rollbackOnFailure=true&useGlobalIds=false&returnEditMoment=false&trueCurveClient=true&attachments=&timeReferenceUnknownClient=false&datumTransformation=&async=false&returnEditResults=true&f=pjson
Example 2
The following is a sample POST request that demonstrates updating an array of features using the applyEdits operation on a feature service layer resource, formatted for readability:
POST /webadaptor/rest/services/SanFrancisco/311Incidents/FeatureServer/0/applyEdits HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
adds=&updates=[
{
"attributes": {
"objectid: 1234567
"req_id": "508389",
"req_type": "Graffiti Complaint - Private Property",
"req_date": "09\/19\/2009",
"req_time": "18:44",
"address": "11TH ST and HARRISON ST",
"x_coord": "6008925.0",
"y_coord": "2108713.8",
"district": "6",
"status": 2
},
"geometry": {
"x": -122.41247978999991,
"y": 37.770630098000083
}
},
{
"attributes": {
"req_id": "508395",
"req_type": "Graffiti Complaint - Public Property",
"req_date": "09\/19\/2009",
"req_time": "19:01",
"address": "13TH ST and MANCHESTER ST",
"x_coord": "6008929.0",
"y_coord": "2108713.9",
"district": "6",
"status": 2
},
"geometry": {
"x": -121.42248867898987,
"y": 38.790630098000452
}
}
]&deletes=&gdbVersion=&rollbackOnFailure=true&useGlobalIds=false&returnEditMoment=false&trueCurveClient=true&attachments=&timeReferenceUnknownClient=false&datumTransformation=&async=false&returnEditResults=true&f=pjson
Example 3
The following is a sample POST request that demonstrates deleting features using the applyEdits operation on a feature service layer resource, formatted for readability:
POST /webadaptor/rest/services/SanFrancisco/311Incidents/FeatureServer/0/applyEdits HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
adds=&updates=&deletes=37, 462&gdbVersion=&rollbackOnFailure=true&useGlobalIds=false&returnEditMoment=false&trueCurveClient=true&attachments=&timeReferenceUnknownClient=false&datumTransformation=&async=false&returnEditResults=true&f=pjson
JSON Response syntax
{
"addResults": [<editResult1>}, <editResult2>],
"updateResults": [<editResult1>}, <editResult2>],
"deleteResults": [<editResult1>}, <editResult2>],
"attachments": {
"addResults": [<attachmentEditResult1>, <attachmentEditResult2>],
"updateResults": [<attachmentEditResult1>, <attachmentEditResult2>],
"deleteResults": [<attachmentEditResult1>, <attachmentEditResult2>]
}
}
JSON Response examples
Example 1
The sample response below demonstrates a general successful response for the applyEdits operation that included adds, updates, and deletes in the request:
{
"addResults": [
{
"objectId": 618,
"success": true
},
{
"success": false,
"error": {
"code": -2147217395,
"description": "Setting of Value for depth failed."
}
}
],
"updateResults": [
{
"objectId": 50,
"success": true
}
],
"deleteResults": [
{
"objectId": 25,
"success": true
},
{
"objectId": 26,
"success": true
}
]
}
Example 2
The example below shows useGlobalids is true and the attachments parameter is set:
{
"addResults": [
{
"objectId": 618,
"globalId": "{74100804-E229-49b8-8CDC-9B5D3EF03EDA}",
"success": true
},
{
"objectId": 619,
"globalId": "{39B856DC-AFE4-4c02-B433-A9361ACD91CF}",
"success": true
}
],
"updateResults": [
{
"objectId": 50,
"globalId": "{9537AFCE-BF6B-4931-93E8-403E12D76916}",
"success": true
}
],
"deleteResults": [
{
"objectId": 25,
"globalId": "{1A9F8368-F9BB-428B-BB03-F45724362DB5}",
"success": true
},
{
"objectId": 26,
"globalId": "{6CE34136-EC3A-40D7-80BF-E1D9BE33812A}",
"success": true
}
],
"attachments": {
"addResults": [
{
"objectId": 500,
"globalId": "{55E85F98-FBDD-4129-9F0B-848DD40BD911}",
"success": true
},
{
"objectId": 501,
"globalId": "{3373EE9A-4619-41B7-918B-DB54575465BB}",
"success": true
}
],
"updateResults": [
{
"objectId": 600,
"globalId": "{8FDD9AEF-E05E-440A-9426-1D7F301E1EBA}",
"success": true
}
],
"deleteResults": [
{
"objectId": 800,
"globalId": "{95059311-741C-4596-88EF-C437C50F7C00}",
"success": true
},
{
"objectId": 801,
"globalId": " {18F43B1C-2754-4D05-BCB0-C4643C331C29}",
"success": true
}
]
}
}
Example 3
The example below shows a constraint rule is violated and rollBackOnFailure is true:
{
"error": {
"code": 400,
"extendedCode": -2147207418,
"message": "Unable to complete operation.",
"details": [
"Violated attribute constraint rule. [Error No: -1, ]",
"Operation rolled back."
]
}
}
Example 4
The example below shows a constraint rule is violated and rollBackOnFailure is false:
{
"addResults": [],
"updateResults": [
{
"objectId": 2,
"globalId": "{B703ACAC-A1A8-4F49-BB19-1E684A67A265}",
"success": false,
"error": {
"code": 1019,
"extendedCode": -2147207418,
"description": "Violated attribute constraint rule. [Error No: -1, ]"
}
},
{
"objectId": 1,
"globalId": "{2FACC38A-3E3E-43A5-A6EB-BC9075407EC8}",
"success": true
}
],
"deleteResults": []
}
Example 5
The example below shows async is true and a status URL is returned:
{
"statusUrl": "https://machine.domain.com/webadaptor/rest/services/testservice/FeatureServer/jobs/sf_j9563cb9e-8cf4-4c99-945d-09e43d408ac7/status"
}
Making a request to a job status URL will return the following response once the operation has completed:
{
"status": "COMPLETED",
"resultUrl": " https://machine.domain.com/webadaptor/rest/directories/arcgisoutput/testservice _MapServer/j9563cb9e-8cf4-4c99-945d-09e43d408ac7.json"
}
The resultUrl returned in the example above gives access to the results of applyEdits:
{
"addResults": [
{
"objectId": 53,
"globalId": "{2AF16CAD-D5B8-4F4C-BF36-432FBF660C0B}",
"success": true
}
],
"updateResults": [ ],
"deleteResults": [ ]
}
Example 6
This example shows an error case in which an edit is attempted for a capability that is not supported and async is set to true. As with example 5, a statusUrl value is returned in the response:
{
"statusUrl": "https://machine.domain.com/webadaptor/rest/services/VRNVA/FeatureServer/jobs/sf_j7aadb493-7987-44cb-9a4c-53e1f9fd97bf/status"
}
Making a request to a job status URL will return the following response once the operation has completed:
{
"status": "COMPLETED",
"resultUrl": "https://machine.domain.com/webadaptor/rest/directories/arcgisoutput/VRNVA_MapServer/j7aadb493-7987-44cb-9a4c-53e1f9fd97bf.json"
}
In this case, however, information returned from the resultUrl value contains the error:
{
"error" : {
"code" : 400,
"message" : "Requested operation is not supported by this service.",
"details" : []
}
}
Example 7
The example below shows a response in which returnEditResults is false and the operation is successful:
{
"success": true
}
Example 8
The sample response below is returned when the request sets the editsUploadId parameter to reference a file where features and attachments were added, updated, and deleted from layer 0:
{
"attachments": {
"addResults": [
{
"success": true,
"globalId": "{FAA66666-766F-47CA-993B-8A3FC57616A1}",
"objectId": 63
}
],
"updateResults": [
{
"success": true,
"globalId": "{469E2233-1F07-43BE-B2C6-155273AA71C5}",
"objectId": 25
}
],
"deleteResults": [
{
"success": true,
"globalId": "{D1DE4DE4-196A-4D00-9773-13E4135C40D5}",
"objectId": 24
}
]
},
"addResults": [
{
"success": true,
"globalId": "{B99CA10D-9FDB-447D-9E8B-44AEDC540629}",
"objectId": 109
}
],
"updateResults": [
{
"success": true,
"globalId": "{D46CA10D-9FDB-447D-9E8B-44AEDC540629}",
"objectId": 22
}
],
"deleteResults": [
{
"success": true,
"globalId": "{69958E11-C6F6-424E-8EEF-E24C0E9B86A6}",
"objectId": 21
}
]
}