/addItem: Add Item

Example usage

https://www.arcgis.com/sharing/rest/content/users/jsmith/addItem
URL=https://www.mymappingapplication.com
title=My Mapping Application
type=Web Mapping Application
tags=web, mapping, application

Description

The Add Item operation (POST only) is used to upload an item file, submit text content, or submit the item URL to the specified user folder depending on documented items and item types. This operation is available only to the specified user.

The request to upload an item file must be a multipart request pursuant to IETF RFC1867. The request to submit text content or a URL can be a standard HTTP POST request.

The user owning the folder automatically becomes the owner of the item. The item is flagged as private (that is, not shared with any group) by default. This can be changed using the Share Item operation. The added item is available to everyone it's shared with at the item resource. The item is also available to the owner at the user item resource, which supports operations to update, delete, move, share, and unshare items.

The filename or URL used for an item must be unique within the particular user's folder.

The addItem operation allows users to optionally create a relationship and share an item in one call. See Add Relationship for parameter information. The same rules apply, with the following exceptions:

• If you specify an originItemId, the new item is added as the destination item.
• If you specify a destinationitemId, the new item is added as the origin item.
• If you specify both, an error is thrown.
• The destination item will inherit all the sharing permissions of the origin item.

The relationship creation is done after the item is created. If the item isn't added correctly, no relationship is created. However, if the item is added correctly, but the relationship fails (that is, it's a bad relationship type, invalid origin or destination item, and so on), the item is deleted.

Asynchronous Uploads

For large file uploads, which take a long time to process, items can be added asynchronously. In this mode, the client checks back with the server on the status of the processing. To invoke the asynchronous mode, the extra parameter of async=true is used with the addItem operation.

• After the file is uploaded, the server returns the ID of the item. The server then processes the file. The response is the same as a synchronous addItem call.
• Status can be checked using the status call and has three possible states: processing, completed, or failed. Completed is returned when processing is finished.
• The status output looks like this:

  {
    "status": "processing",
    "statusMessage": "processing",
    "itemId": "ddb1838f5a76478894698d371be3a2b6"
  }
  

• A status error message looks like this:

  {
    "status": "failed",
    "statusMessage": "Item 'mexicoWebMercator.sd' already exists. Set the 'overwrite' flag to true if you want to overwrite."
    "itemId": "ddb1838f5a76478894698d371be3a2b6"
  }
  

Multipart Uploads

Large files can also be uploaded in parts from a client who has the ability to split files into smaller parts.

To initiate a multipart upload, the client passes in the multipart=true parameter to this addItem operation along with the filename. In multipart mode, those are the only two parameters needed, and all others will be ignored.

Once the multipart update is initiated, the Add Part operation is used to upload each part of a file, and finally the Commit operation is used to complete the upload.

No item properties can be passed into the multipart call. If the uploaded file is not a package that includes item information (see additional details in the next section), then an Update Item call must be made to update the item's information.

Item Info

If the item is an uploaded ZIP file or an ArcGIS package and if it contains an esriinfo folder, then all files and subfolders in the esriinfo folder will be extracted and available through the item info file URLs.

For instance, if the structure of the uploaded file is as follows:

Zip file (*.mpk, *.lpk)
 |-- esriinfo (folder)
           |-- iteminfo.xml (item card)
                     |-- subfolder
                               |-- thumbnail.jpg

the iteminfo.xml file is available at the following URL:

https://server/sharing/rest/content/items/<itemId>/info/iteminfo.xml

And similarly, thumbnail.jpg is available at the following URL:

https://server/sharing/rest/content/items/<itemId>/info/subfolder/thumbnail.jpg

Further, iteminfo.xml represents the "item card". Users can provide some basic information for the item, such as name, title, thumbnail, and so on, in this file. If you specify the thumbnail and documentation properties in this item card, they should be paths relative to the esriinfo folder. In the above case, the thumbnail should be specified as follows:

<ESRI_ItemInformation>
   ...
   <thumbnail>subfolder/thumbnail.jpg</thumbnail>
   ...
</ESRI_ItemInformation>

You do not need to bundle this information with the file that you upload. This information can be submitted as query parameters, such as name, title, and so on, along with the file or URL parameters. Additionally, this information can be specified using the Update Item operation.

Request parameters

Parameter	Details
[Common Parameters]	For a complete listing, see Common parameters.
file	The file to be uploaded. If uploading a file, the request must be a multipart request.
dataUrl	The URL where the item can be downloaded. The resource will be downloaded and stored as a file type. Similar to uploading a file to be added, but instead of transferring the contents of the file, the URL of the data file is referenced and creates a file item. Please see the implementation details section below which discusses this parameter in further details.
url	The URL of the item to be submitted. The URL can be a URL to a service, a web mapping application, or any other content available at that URL. Example url=https://server.arcgisonline.com/ArcGIS/rest/services/ESRI_Imagery_World_2D/MapServer
text	The JSON content for the item to be submitted. Example text={'myAttribute':'myValue'}
relationshipType	The type of relationship between the two items. See Relationship types for a complete listing of types. Example relationshipType=WMA2Code
originItemId	The item ID of the origin item of the relationship. Example originItemId=bb297e5eac6d489e85993d5e4d4e4a20
destinationItemId	The item ID of the destination item of the relationship. destinationItemId=8d292f9b0cd5457bbdad84c02223ffb8
async	If true, the file is uploaded asynchronously. If false, the file is uploaded synchronously. The default is false. Values: true | false
multipart	If true, the file is uploaded in multiple parts. See the Multipart Uploads section above for more information. Values: true | false
filename	The filename being uploaded in multipart mode. Required if multipart is true. Values: true | false
serviceProxyParams	A JSON object that provides rate limiting and referrer checks when accessing secured services. Example serviceProxyParams={"hitsPerInterval":2,"intervalSeconds":60,"referrers":["https://<servername>"]}
createAsServiceProxy	If true, a service URL is added as a proxy item without embedding credentials. It can be used to take advantage of the portal sharing model for security, hide actual service URLs, rate limiting and referrer checks, etc. Values: true | false
itemIdToCreate	New at 10.8.1. The item ID of the item. The item ID must not exist and must be 32 alphanumeric values. Note: itemIdToCreate applies to ArcGIS Enterprise Portal only. Example itemIdToCreate=832157e321df46f721f9ededbe34ac58
[Item Info Parameters]	For a complete listing of all item info parameters, see Item parameters.

Service Proxy parameters

ArcGIS Online and ArcGIS Enterprise portal users can register premium services, as well as services published on their own server, as secured service proxies. If working with secured services, you have the option to save the username and password credentials directly with the item. Setting the serviceProxyParams provides additional control over how these services are accessed by supplying rate limiting and referrer checks. In other words, by setting these parameters, you provide more control over who can access these services and how much they can use them.

The serviceProxyParams JSON object used to set rate limiting and referrer checks on secured services is described below.

{
  "error": {
    "code": 429,
    "messageCode": "CONT_0049",
    "message": "Rate limit exceeded. Please try again later.",
    "details": []
  }
}

Note:

Both hitPerInterval and IntervalSeconds need to be greater than zero (0) in order for rate limiting to work.

A sample serviceProxyParams JSON object is as follows:

{
  "hitsPerInterval":2,
  "intervalSeconds":60,
  "referrers":["https://server1","https://server2"],"https://*arcgis.com]  //*.arcgis.com allows any subdomain from arcgis.com to be added
}

Response properties

Examples

https://www.arcgis.com/sharing/rest/content/users/jsmith/addItem
URL=https://www.mymappingapplication.com
title=My Mapping Application
type=Web Mapping Application
tags=web, mapping, application

dataUrl=https://mysharedserver/CSV/restaurants.csv
title=Restaurants
type=CSV
tags=restaurants, web

https://webadaptorhost.domain.com/webadaptorname/sharing/rest/content/users/jsmith/addItem
Parameters (datastore JSON information formatted in pJSON)
text={
  "type":"cloudstore",
  "info": {
    "isManaged": false,
    "connectionString": {
      "accessKeyId": "example_input_key",
      "secretAccessKey": "secret_key",
      "region": "cn-east-2",
      "defaultEndpointProtocol": "https",
      "credentialType": "accesskey"
    },
    "objectStore": "bucketName/folderName"
  },
  "path": "/cloudStores/storeName",
  "provider": "Huawei"
}
title=myCloudStore
type=Data Store

JSON Response syntax

{
  "success": true | false,
  "id": "<item id>",
  "folder": <folder id>
}

JSON Response example

{
  "success": true,
  "id": "17dd19b627b74068a6f3292c7ae0d88a",
  "folder": null
}