Add Item

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 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:

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

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.

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:

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

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

http://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=http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_Imagery_World_2D/MapServer

text

The text content for the item to be submitted.

Example: text=Any+plain+text+content

relationshipType

The type of relationship between the two items. See Relationship types for a complete listing of types.

Example: WMA2Code

originItemId

The item ID of the origin item of the relationship.

Example: bb297e5eac6d489e85993d5e4d4e4a20

destinationItemId

The item ID of the destination item of the relationship.

Example: 8d292f9b0cd5457bbdad84c02223ffb8

async

If true, the file is uploaded asynchronously. If false, the file is uploaded synchronously.

Default is false.

Example: async=true

multipart

If true, the file is uploaded in multiple parts. See the Multipart Uploads section above for more information.

filename

The filename being uploaded in multipart mode. Required if multipart=true.

serviceProxyParams

A JSON object that provides rate limiting and referrer checks when accessing secured services.

Example: serviceProxyParams:{"hitsPerInterval":2,"intervalSeconds":60,"referrers":["http://<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.

Example: createAsServiceProxy=true

[Item Info Parameters]

For a complete listing of all item info parameters, see Item parameters.

Implementation details for using the dataURL parameter

  • The referenced dataUrl, has to be an unsecured URL where data can be downloaded.
  • This operation is asynchronous, therefore the client should check the item's status before using. If the status is "completed", the resource is downloaded and the file item is added successfully.
  • If the resource supports Byte Ranges and the content length is larger than 500kb, Range GET's are used to download the file in parts.
  • Multiple parallel threads download the file parts and perform a file-based merge on them. This is not performed in-memory as to avoid buffering. If a part can't be downloaded, it attempts once more before failing. All parts needs to be downloaded successfully before the item can be created.
  • If overwrite=true an existing file is updated.

Service Proxy Parameters

ArcGIS Online and Portal for ArcGIS 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.

Parameter

Details

hitsPerInterval

Number of requests that will be allowed within a specifed time interval of intervalInSeconds. Default value is "2".

intervalSeconds

Integer value indicating the interval time in seconds. Default value is "60".

referrers

Array of referrers allowed to access service.

If rate limit is exceeded, an error will occur.

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

NoteNote:

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

Property

Details

success

Indicates if the operation was successful.

id

The ID of the created item.

folder

The folder in which the item was created.

Example Usages

URL for Add Item

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

dataUrl for Add Item - this example shows adding a reference to a CSV file

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

JSON Response Syntax

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

JSON Response Example

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

10/6/2017