# Outer ID usage

Some of our customers would like to provide and use the resources with their unique identifiers (OUTER_ID) as opposed to the ones generated by us (API_ID), for that we offer the below described solution.

We recommend the use of the Outer ID only in case of a batch request, when an additional related resource must be created during the creation of the original one. Without Outer ID, responses to the requests will only be returned together in the batch at the end of the batch process, therefore e.g. we will not know what resource ID to use for the corresponding product description (Product Description resource) after adding a product (Product resource). However, if we create the product with Outer ID, we will be able to refer to it while adding the description, regardless of whether we know the actual internal resource ID of the product. This solution will be used before the appearance of the less complicated Resource Extend, therefore if a resource has an extended version, e.g.: Product Extend Resource, we recommend using that version instead of batching with Outer ID.

In addition, if we do choose the Outer ID solution, storage on client side is not recommended.

The following examples are only illustrations, therefore the complete API request and response is not included.

# Resource creation

# POST

If the ID is not specified in case of POST, the system will generate one and will return it as a response. If we specify the ID, the system will store it as an Outer ID and will assign it to the resource. This ID can be referred to during GET, PUT, DELETE methods.

E.g. product request without Outer ID:

method:	POST
url:	http://shopname.api.myshoprenter.hu/products
headers:	Accept:application/json Content-Type:application/json

{
  "data": {
    "sku": "SKU-11",
    "modelNumber": 0,
    "orderable": 1,
    "price": 139900.0000,
    "multiplier": 1.0000,
    "multiplierLock": 0
  }
}

Response:

HTTP STATUS CODE: 200 or 201

{
  "response": {
    "href": "http://shopname.api.myshoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTI0NTE=",
    "id": "cHJvZHVjdC1wcm9kdWN0X2lkPTI0NTE=",
    "innerId": "1",
    "sku": "SKU-11"
  }
}

Product request with OUTER_ID:

method:	POST
url:	http://shopname.api.myshoprenter.hu/products/SKU-11
headers:	Accept:application/json Content-Type:application/json

{
  "data": {
    "sku": "SKU-11",
    "modelNumber": 0,
    "orderable": 1,
    "price": 139900.0000,
    "multiplier": 1.0000,
    "multiplierLock": 0
  }
}

Response:

HTTP STATUS CODE: 200 or 201

{
  "response": {
    "href": "http://shopname.api.myshoprenter.hu/products/SKU-11",
    "innerId": "1",
    "id": "SKU-11",
    "sku": "SKU-11"
  }
}

Remark: The item number (SKU) is entered as OUTER_ID in the above example, but this may differ.

# PUT

API_ID or OUTER_ID is mandatory in case of PUT in the URI. If this identifier is OUTER_ID, then the system requires an already existing resource, otherwise everything proceeds as described in POST method. This means, that it is not possible to create new resources with PUT and OUTER_ID, unlike creating with API_ID.

# GET

We can refer to OUTER_ID in URI in case of GET during the request, if the resource has already been created with an OUTER_ID.

# DELETE

If an OUTER_ID exists for a resource, it is deleted along with the resource in case of deletion.

# In case of an existing resource

If you would like to assign OUTER_ID to an already existing resource, or want to modify the current one, we can offer you a solution to do so from now on. All resources have an id property, which is either the OUTER_ID, if exists, or the internally generated API_ID. Example for a resource:

{
  "response": {
    "href": "http://shopname.api.myshoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTk2",
    "id": "cHJvZHVjdC1wcm9kdWN0X2lkPTk2",
    "innerId": "96",
    "sku": "BI-NAT004HU30",
    "price": "2759",
    "stock1": "10",
    "stock2": "20",
    "stock3": "0",
    "stock4": "0"
  }
}

# POST/PUT

In the case of POST and PUT requests, id property must simply be included in the sent data. If no OUTER_ID exists for the given resource, it will be created. If there is one, it will be overwritten.

Example for a POST/PUT request:

method:	POST/PUT
url:	http://shopname.api.myshoprenter.hu/products/cHJvZHVjdC1wcm9kdWN0X2lkPTk2
headers:	Accept:application/json Content-Type:application/json

{
  "data": {
    "id": "TestOuterID",
    "price": 2760,
    "stock1": 12
  }
}

TestOuterID has been sent as the id property in this case, so it is assigned as the OUTER_ID to the given resource. So the newly set OUTER_ID will be the id property in the API response. Furthermore, the access of the given resource will also be changed.

{
  "response": {
    "href": "http://shopname.api.myshoprenter.hu/products/TestOuterID",
    "id": "TestOuterID",
    "innerId": "96",
    "sku": "BI-NAT004HU30",
    "price": "2760",
    "stock1": "12"
  }
}

# GET

We can refer to OUTER_ID in the URI in case of GET requests:

/products/TestOuterID

# DELETE

If an OUTER_ID exists for a resource, it is deleted along with the resource in case of deletion.

# Incorrect use of OUTER_ID

It is very important to highlight that Outer ID has been designed to send batch requests and not for special operations such as item number synchronization. The reason for this is that the activities on the administration interface of the shops are not synchronized with the deletion, overwriting and use of Outer IDs. As a result, if a product is deleted on the administration interface of a shop, its Outer ID will not be deleted.

← API Batch processor Extend Resource →