- URL:https://[root]/content/users/[userName]/addItem(POST only)
Example usage
Note:
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 following is a sample ArcGIS Online POST request for the addItem operation:
POST /sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: org.arcgis.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
url=https://www.mymappingapplication.com&title=My Mapping Application&type=Web Mapping Application&tags=web, mapping, application&f=pjsonThe following is a sample ArcGIS Enterprise POST request for the addItem operation:
POST /webadaptor/sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
url=https://www.mymappingapplication.com&title=My Mapping Application&type=Web Mapping Application&tags=web, mapping, application&f=pjsonDescription
The addItem operation allows a user 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.
Note:
When submitting the item to a specified user folder, the user who owns the folder automatically becomes the owner of the item. The item is flagged as private by default, and will not be shared with any group. This can be changed using the Share Item operation. Once shared, the added item is available at the item resource level. This item is also available to the owner at the user item resource level, which supports the Update, Delete, Move, Share, and Unshare items operations. The file name or URL used for an item must be unique within the particular user's folder.
This operation is available only to the specified user. This operation also allows users to optionally create a relationship and share an item in one call. 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 returned.
- The destination item will inherit all the sharing permissions of the origin item.
The relationship creation is finished 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.
Additional considerations
The following sections outline additional behaviors or features for the addItem that should be considered before performing this operation
Asynchronous uploads
Large files take a long time to process when uploaded. Rather than processing the request to add an item synchronously, this operation can be performed asynchronously. In this mode, the client checks back with the server for the job's status. To utilize asynchronous mode, the async parameter should be set to true. Once the request is submitted, the JSON response will return the item ID of the added item, as well as the request's current status and status message:
{
"status": "processing",
"statusMessage": "processing",
"itemId": "ddb1838f5a76478894698d371be3a2b6"
}The status can be checked using the Status operation. When polled, the status can return as one of three possible states: processing, completed, or failed. The status message will return information relevant to the job's current status. For example, the status message below details why the request failed:
{
"status": "failed",
"statusMessage": "Item 'mexicoWebMercator.sd' already exists."
"itemId": "ddb1838f5a76478894698d371be3a2b6"
}Multipart uploads
Clients that have the ability to split large files into smaller parts can utilize multipart uploads. To initiate a multipart upload, the multipart parameter should be set to true. When uploading multiple file parts, only the multipart and filename parameters are required. All other parameters will be ignored. Once the multipart upload has been initiated, the Add Part operation is used to upload each part of the file, which are then committed 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, the Update Item operation must be called to update the item's information.
Chunked transfer encoding
The use of chunked transfer encoding is not recommended. There is an upload limit of 50mb when using chunked transfer. Because the size of an upload cannot be checked prior to transfer, the operation may fail unexpectedly if the limit is reached.
Item information
If the item is an uploaded .zip file, or an ArcGIS package, and it contains an esriinfo folder, all files and subfolders in the esriinfo folder will be extracted and available through the Item Info File resource. To demonstrate, the example below represents the structure of an uploaded .zip file:
Zip file (*.mpk, *.lpk)
|-- esriinfo (folder)
|-- iteminfo.xml (item card)
|-- subfolder
|-- thumbnail.jpgThe iteminfo.xml in the structure above will be available from the Item Info File resource:
https://machine.domain.com/webadaptor/sharing/rest/content/items/[itemID]/info/iteminfo.xmlThe iteminfo.xml file represents the item card. Users can provide some basic information for the item, such as the item's name, title, thumbnail in this file. If you specify the thumbnail and documentation properties in this item card, they must be paths relative to the esriinfo folder. In the above case, the thumbnail must be specified as follows:
<ESRI_ItemInformation>
...
<thumbnail>subfolder/thumbnail.jpg</thumbnail>
...
</ESRI_ItemInformation>However, you do not need to bundle this information with the file at the time of uploading. This information can be submitted as query parameters (such as name and title) along with the file or url parameters. This information can also be specified using the Update Item operation.
In addition to thumbnail information being returned in the iteminfo.xml file, the thumbnail file is available at the following location:
https://server/sharing/rest/content/items/<itemId>/info/<subfolder>/thumbnail.jpgRequest parameters
| Parameter | Details |
|---|---|
| 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. The referenced URL must be an unsecured URL where the data can be downloaded. This parameter requires the operation to be performed asynchronously. Once the job status returns as complete, the item can be downloaded and the item is added successfully. If the item supports Byte Ranges, and the content length is larger than 500kb, a Range GET is 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 in order to avoid buffering. If a part cannot be downloaded, the system will attempt once more before failing. All parts must be downloaded successfully before the item can be created. |
| 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 |
| text | The JSON content for the item to be submitted. Example |
| relationshipTypes | The type of relationship between the two items. See Relationship types for a complete listing of types. Example |
| originItemId | The item ID of the origin item of the relationship. Example |
| destinationItemId | The item ID of the destination item of the relationship. |
| multipart | If true, the file is uploaded in multiple parts. See the Multipart uploads section above for more information. Values: true | false |
| filename | The file name 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. For more information on serviceProxyParams properties, see the Service proxy properties section below. Example |
| 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, for rate limiting, for referrer checks, and so on. 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 only to ArcGIS Enterprise. Example |
| title | The title of the item. This is the only name that users and applications use for the item. There is no concept of display names or aliases in the Sharing API. The item title is limited to 256 alphanumeric characters. Example |
| thumbnail | The pathname to the thumbnail image to be used for the item. For best results, images that are 600 x 400 pixels or larger with an aspect ratio of 1.5:1 are recommended. Supported file formats are PNG, GIF, and JPEG with a maximum file size of 10 MB. This will not be a reference to the file but the file itself that is stored on the sharing servers. Item thumbnail can be retrieved at different dimensions by specifying a URL parameter w for the desired image width: Example Supported retrievable thumbnail widths for item are 200 pixels (default), 400 pixels, 800 pixels, and 2400 pixels, with an aspect ratio of 1.5:1. Other specified sizes will be snapped to the next highest supported dimension for query. If the original image dimension is smaller than the size queried, the original image will be returned. Example |
| thumbnailurl | The URL to the thumbnail image to be used for the item. The recommended image size is 200 x 133 pixels. Acceptable image formats are PNG, GIF, and JPEG. The maximum file size for an image is 1 MB. Example |
| metadata | The file that stores the metadata information on an item. It's stored in the metadata folder under esriinfo, for example, /sharing/rest/content/items/<itemid>/info/metadata/metadata.xml. Example |
| metadataEditable | Indicates if the organization has metadata enabled. If true, all members of the organization can view the metadata. Only item owners and administrators can update metadata. If false, no one in the organization can access the metadata. Values: true | false |
| metadataFormats | Metadata style used for organization. The default style is iso19139. Values: fgdc | inspire | iso19139 | iso19139-3.2 | iso19115 |
| type | The type of the item. Must be drawn from the list of supported types. See Items and item types for a list of the supported types. Example |
| typeKeywords | Adds additional type keywords to the item. Type keywords describe the type and should logically apply to all items of that type. Type keywords can be applied to any type of item, including hosted feature services. See Items and item types for a list of the different predefined type keywords that will be automatically added based on the supplied type. Syntax Example |
| description | An item description less than 64 Kb. Example |
| tags | A comma-delimited list of tags for the item. Tags are words or short phrases that describe the specific item. Syntax Example |
| snippet | Snippet or summary for the item. Limit this brief descriptive text to 2048 characters. Example |
| extent | The item's bounding rectangle. Example Example |
| spatialReference | The coordinate system of the item. Example |
| accessInformation | Credits the source of the item. Example |
| licenseInfo | Includes any license information or restrictions. Example |
| culture | The item locale (language and country) information. If the added item is a package, the culture parameter in the ESRI_ItemInformation tag is read and used if available. If the culture is not specified by the user, or not provided in the package, the culture is set using the Accept-Language HTTP header sent by the browser. If the browser does not provide a locale, no default is set. The record will have no locale, and it will not be indexed under a certain language or country. The format for a culture code is based on a language code and country code, separated by a dash. The language code is based on the two-letter codes found at Library of Congress' Codes for the Representation of Names of Languages. The country code is based on the two-letter codes found by searching the ISO Online Browsing Platform. |
| properties | A JSON object that primarily applies to system requirements, Terms and Conditions, version, supported platforms, YouTube video ID, etc associated with the application. |
| appCategories | An array that primarily applies to a list of categories that the application item is applicable to. |
| industries | An array that primarily applies to industries associated with the application. |
| languages | An array that primarily applies to languages associated with the application. |
| largeThumbnail | The URL to the thumbnail used for the application. This parameter primarily applies to thumbnail associated with an application. |
| banner | The URL to the banner used for the application. This parameter primarily applies to the banner associated with an application. |
| screenshot | The URL to the screenshots used for the application. This parameter primarily applies to screenshots associated with an application. |
| listingProperties | A JSON object consists of listing properties when the item is listed in ArcGIS Marketplace. For information on the listingProperties properties, see the Listing properties section below. |
| serviceUsername | Set the username on a secure on-premise ArcGIS Server service. It is valid on Map Services, Feature Services and Image Services only. Example |
| servicePassword | Set the password on a secure on-premise ArcGIS Server service. It is valid on Map Services, Feature Services, and Image Services only. Example |
| serviceProxyFilter | A JSON object with category, sourceCountry and searchExtent properties that is used to restrict service item response results based on specified filter, such as limit results returned from a geocode service based on defined filters. This parameter is only applicable to Geocoding Service type items. The three properties can be used independently or in any combination. When combined, they are applied as an Boolean AND operator. Syntax Example |
| categories | A JSON array or comma separated list of categories to add to the item. Example |
| async | If true, the file is uploaded asynchronously. If false, the file is uploaded synchronously. The default is false. Values: true | false |
| f | The response format. The default format is html. Values: html | json | pjson |
Listing properties
A listing is specified as a JSON object. Its syntax and properties are as follows:
| Property | Details |
|---|---|
| licenseType | The type of license offered by the listing. The free value specifies whether the listing will be provisioned to the customer for free. The ela value specifies whether an Enterprise Level Agreement needs to be agreed upon between the vendor and the customer. The consumption value specifies a consumption-based model, which typically applies to data services. The preprovisioned value specifies whether the item is preprovisioned and ready to use. Values: free | ela | consumption | preprovisioned |
| listingAccess | Indicates whether the listing is public or private. Values: public | private |
| priceDesc | Text that describes the pricing details of this listing. This property is not required for free listings. |
| creditsPerTransaction | The number of credits that will be charged to the customer per transaction. This property only applies to consumption-based listings. |
| trialSupported | Indicates whether or not the listing supports trials. Values: true | false |
| trialDuration | Duration of the trial (in days). This property only applies when trialSupported is true. |
| ecommerceEnabled | Indicates whether or not the listing is e-commerce enabled. Values: true | false |
| licenseBy | Listing licensing model. The default is licenseByOrg if the property is missing. Values: licenseByUser | licenseByOrg |
Service proxy properties
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 limitations, 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.
| Property | Details |
|---|---|
| hitsPerInterval | Number of requests that will be allowed within a specified time interval of intervalInSeconds. The default value is 2. Note:Both hitPerInterval and IntervalSeconds must be greater than zero (0) for rate limiting to work. |
| intervalSeconds | Integer value indicating the interval time in seconds. The default value is 60. |
| referrers | Array of referrers allowed to access service. |
The example below demonstrates a sample serviceProxyParams JSON object:
{
"hitsPerInterval":2,
"intervalSeconds":60,
"referrers":["https://server1","https://server2"],"https://*arcgis.com] //*.arcgis.com allows any subdomain from arcgis.com to be added
}When serviceProxyParams has been defined, if the rate limit is exceed an error message will be returned:
{
"error": {
"code": 429,
"messageCode": "CONT_0049",
"message": "Rate limit exceeded. Please try again later.",
"details": []
}
}Additional example usage
Add a reference to a .csv file
The following examples for ArcGIS Online and ArcGIS Enterprise are sample POST requests that demonstrate using the addItem operation to add a reference to a .csv file.
ArcGIS Online:
POST /sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: org.arcgis.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
dataUrl=https://mysharedserver/CSV/restaurants.csv&title=Restaurants&type=CSV&tags=restaurants, webArcGIS Enterprise:
POST /webadaptor/sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
dataUrl=https://mysharedserver/CSV/restaurants.csv&title=Restaurants&type=CSV&tags=restaurants, webAdd item using the data store's information
The following example for ArcGIS Enterprise is sample POST requests that demonstrate adding a data store item to a portal with the data store's JSON information. The sample request below have been formatted for readability.
POST /webadaptor/sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
https://machine.domain.com/webadaptorname/sharing/rest/content/users/jsmith/addItem&text={
"type": "cloudstore",
"info": {
"isManaged": false,
"connectionString": {
"accessKeyId": "example_input_key",
"secretAccessKey": "secret_key",
"region": "us-west-2",
"defaultEndpointProtocol": "https",
"credentialType": "accesskey"
},
"objectStore": "bucketName/folderName"
},
"path": "/cloudStores/storeName",
"provider": "amazon"
}&title=myCloudStore&type=Data StoreJSON 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 |
JSON Response syntax
{
"success": true | false,
"id": "<item id>",
"folder": <folder id>
}JSON Response example
{
"success": true,
"id": "17dd19b627b74068a6f3292c7ae0d88a",
"folder": null
}