Get External Service Data

As a Marketplace Сonsumer, you can perform an HTTP request to an external service (ExtSvc) such as REST API or AWS S3 bucket using Marketplace External Proxy Service (Marketplace EPS). The request will be authenticated, processed, recorded through Technical Account for billing, and redirected to an external service. You will receive a response from an external service in its original form, with the same HTTP response code and the same response header as if you would call the external service directly. If an external service fails with an error, you will receive this error in its original form.

Request an External REST API

To post a successful call to Marketplace EPS tunnel, consult the external service provider's API documentation.

A typical workflow includes the following steps:

  1. Use the GET, POST, PUT, or DELETE method according to the external service provider's documentation provided in the listing.

  2. Use p.hereapi.com/tunnel/ before the endpoint URL that you find in the documentation. A typical request URL structure would be as follows:

   https://p.hereapi.com/tunnel/{domain}/{pathToExternalServiceResource}?{optionalRequestParameters}
  • p.hereapi.com - Base URL
  • {domain} - ExtSvc domain (identifier) to forward an HTTP request to
  • {pathToExternalServiceResource} - ExtSvc resource path to combine with the domain
  • {optionalRequestParameters} - Any request parameters required by an ExtSvc resource

  1. Fill in the query parameters, headers, and request body as described in the external service provider's documentation.

  2. Use the HERE platform Bearer Token for authentication and disregard authentication protocols that you may find in the external service provider's documentation. Marketplace EPS will handle authentication and authorization for you.

  1. Post a request to an external REST API using the format provided above. For example, https://p.hereapi.com/tunnel/dataservice.company-name.com/locations/v1/topcities/50. Use the HERE account credentials for this call.

    Find the domain and resource path for the request in an API endpoint example on the subscription details page:

    External REST API data subscription in HERE Marketplace
    Figure 1. External REST API data subscription in HERE Marketplace

    In case there is an asterisk (wildcard) at the end of the resource path, you may add further path details after a slash. You shouldn't put an asterisk in your request URL, though.

    For information on possible resource path modifications and optional request parameters, see information by the service provider in the corresponding subscription.

  2. Marketplace EPS authenticates you and inspects the dataservice.company-name.com part, also known as a service provider domain, to validate this previously provisioned domain.

  3. Marketplace EPS inspects the locations/v1/topcities/50 part, also known as a service provider resource, and checks if you have access to this resource in the specified domain. If you don't have access, the service returns an error. If you have access, step 4 follows.
  4. Marketplace EPS combines the domain and path and prepares to execute the request https://dataservice.company-name.com/locations/v1/topcities50. At the same time, Marketplace EPS extracts the Marketplace provider's API key stored in a database and appends it to the request (in the case of simple API key-based authentication). For example, if a previously provisioned API key is ABCDEFGH, the resulting request will be https://dataservice.company-name.com/locations/v1/topcities/50?api_key=ABCDEFGH.
  5. The request is performed and the response is read.
  6. The response is recorded and submitted to Technical Account to perform proper billing and analytics. This is a background operation and does not affect the call latency.
  7. The response is forwarded back to you with the original payload and HTTP headers. In case of failure, an HTTP response code with an error payload is returned.

Request an External AWS S3 Bucket

As a Marketplace Сonsumer, you can request external resources stored as cloud objects in Amazon (AWS) S3 buckets through Marketplace External Proxy Service. Make requests to the entire bucket or its specific directory using the following formats, respectively:

Entire bucket resources
Specific bucket directory resources
GET https://p.hereapi.com/aws/s3/buckets/{bucketName}/resources
GET https://p.hereapi.com/aws/s3/buckets/{bucketName}/resources?path={somePath}
  • p.hereapi.com - Base URL
  • {bucketName} - S3 bucket name (identifier)
  • {somePath} - Resource path:
    • dir_1/
    • dir_1/sub_dir_1/

A typical workflow includes the following steps:

  1. Post a request to an external AWS S3 bucket using the format provided above. For example, https://p.hereapi.com/aws/s3/buckets/s3extproxytest/resources?path=dir_1/. Use the HERE account credentials for this call.

    Find the S3 bucket name and resource path for the request in an API endpoint example on the subscription details page:

    External AWS S3 data subscription in HERE Marketplace
    Figure 2. External AWS S3 data subscription in HERE Marketplace

    In case there is an asterisk (wildcard) at the end of the resource path, you may add further path details after a slash. You shouldn't put an asterisk in your request URL, though.

    For information on possible resource path modifications, see information by the service provider in the corresponding subscription.

  2. You get a response with a list of objects to download.

    Response example:

    Status code 200

    Body:

    Entire bucket resources
    Specific bucket directory resources
    {
          "pageId": 0,
          "nextPageId": 0,
          "isNextPage": false,
          "objectsCount": 1,
          "subDirectories": [
          {
              "key": "dir_1/",
              "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_1/"
          },
          {
              "key": "dir_2/",
              "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_2/"
          },
          {
              "key": "dir_3/",
              "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_3/"
          },
          {
              "key": "dir_4/",
              "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_4/"
          },
          {
              "key": "dir_5/",
              "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_5/"
          }
          ],
          "directoryContent": [
          {
          "bucketName": "s3extproxytest",
          "key": "TEST",
          "resourceApiUrl": "/aws/s3/buckets/s3extproxytest/resources/object?path=TEST",
          "size": 57,
          "lastModified": "2021-02-25T17:05:40.000+00:00"
          }
          ]
      }
    {
        "pageId": 0,
        "nextPageId": 0,
        "isNextPage": false,
        "objectsCount": 3,
        "subDirectories": [
        {
            "key" : "dir_1/subdir_1/",
            "directoryApiUrl" : "/aws/s3/buckets/s3extproxytest/resources?path=dir_1/subdir_1/"
        },
        {
            "key" : "dir_1/subdir_2/",
            "directoryApiUrl" : "/aws/s3/buckets/s3extproxytest/resources?path=dir_1/subdir_2/"
        }
        ],
        "directoryContent": [
        {
            "bucketName" : "s3extproxytest",
            "key" : "dir_1/0a415506de72cde298f0f85b0a60bb9e1cd09dba.jpg",
            "resourceApiUrl" : "/aws/s3/buckets/s3extproxytest/resources/object?path=dir_1/0a415506de72cde298f0f85b0a60bb9e1cd09dba.jpg",
            "size" : 1292159,
            "lastModified" : "2021-03-01T16:07:36.000+00:00"
        },
        {
            "bucketName" : "s3extproxytest",
            "key" : "dir_1/13136c8506f89055fd05ec441855f8af9431c966.jpg",
            "resourceApiUrl" : "/aws/s3/buckets/s3extproxytest/resources/object?path=dir_1/13136c8506f89055fd05ec441855f8af9431c966.jpg",
            "size" : 147628,
            "lastModified" : "2021-03-01T16:07:51.000+00:00"
        },
        {
            "bucketName" : "s3extproxytest",
            "key" : "dir_1/14ec91f6eac37c60c3b5e6198910d2bef55f65dd.jpg",
            "resourceApiUrl" : "/aws/s3/buckets/s3extproxytest/resources/object?path=dir_1/14ec91f6eac37c60c3b5e6198910d2bef55f65dd.jpg",
            "size" : 383339,
            "lastModified" : "2021-03-01T16:07:45.000+00:00"
        }
        ]
    }
    • resourceApiUrl - List of objects (files) in the current directory to download

  3. Request an object to download by indicating the object URL provided in the list of objects of the resources request. Use the following format:

    GET https://p.hereapi.com/aws/s3/buckets/{bucketName}/resources/object?path={somePath}

  4. You get a pre-signed URL to download the object.

    Response example:

    Status code 200

    Body:

    https://s3extproxytest.s3.eu-central-1.amazonaws.com/dir_1/?x-consumer-id=null&  X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210603T125418Z&X-Amz-SignedHeaders=host&  X-Amz-Expires=3599&  X-Amz-Credential=AKIAXGEF5U6TPFKR4FEI%2F20210603%2Feu-central-1%2Fs3%2Faws4_request&  X-Amz-Signature=46e3ba3f84a1d4628fd7fa987e935250263fdd2e410ad70f805115430bcc5d13

    You can also skip the steps above and instantly get pre-signed URLs to all contained objects using this single request:

    GET https://p.hereapi.com/aws/s3/buckets/{bucketName}/resources/directory?path={somePath}

    Response example:

    Status code 200

    Body:

     {
     "pageId" : 0 ,
     "nextPageId" : 0 ,
     "isNextPage" : false ,
     "objectsCount" : 3 ,
     "subDirectories": [
     {
         "key": "dir_1/subdir_1/",
         "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources/directory?path=dir_1/subdir_1/"
     },
     {
         "key": "dir_1/subdir_2/",
         "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources/directory?path=dir_1/subdir_2/"
     }
     ],
     "signedUrls": {                 
         "dir_1/7648dd3581b8dc9d920d12bf8b85fa29465d1d28.jpg": "https://s3extproxytest.s3.eu-central-1.amazonaws.com/dir_1/7648dd3581b8dc9d920d12bf8b85fa29465d1d28.jpg?x-consumer-id=HERE&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210913T104444Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=AKIAXGEF5U6TPFKR4FEI%2F20210913%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=36cdb3f1297ed964536916b928046897b9f18008537247a597e8e5e951d5b461",
         "dir_1/de60a0fff76f28918ab764d7417fa0db724da22f.jpg": "https://s3extproxytest.s3.eu-central-1.amazonaws.com/dir_1/de60a0fff76f28918ab764d7417fa0db724da22f.jpg?x-consumer-id=HERE&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210913T104444Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=AKIAXGEF5U6TPFKR4FEI%2F20210913%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=55deb0fca00d6e1dc39f1dd5b454db78ced661e79985e70ece4afd538d6db529",
         "dir_1/9fdb285d503ce28c87901666c18a2583143f5e6d.jpg": "https://s3extproxytest.s3.eu-central-1.amazonaws.com/dir_1/9fdb285d503ce28c87901666c18a2583143f5e6d.jpg?x-consumer-id=HERE&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210913T104444Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=AKIAXGEF5U6TPFKR4FEI%2F20210913%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=e2d5d88930ac6d9aefd0053a98c06b54c35cc407625e8ea88db2e08dd64a5fc4"
     }
 }

  5. Alternatively to requesting a pre-signed URL to download an object, you may request temporary security credentials to make requests for AWS resources using the AWS CLI or AWS API. Use the following format:

    GET https://p.hereapi.com//aws/s3/buckets/{bucketName}/credentials

    Response example:

       {
       "accessKeyId": "ASIAXGEF5U6TGQBTBEG3",
       "secretAccessKey": "Aweqo1WiZc8q5z4qTFtgSwnAkf1bltaE8/TI+ypy",
       "sessionToken": "FwoGZXIvYXdzEFgaDPmnt1gHSnE7jTR+EiKfAhnqCapu+Eu0nBK3+7oH2ycukTl5x47pOd1IRrM0qAVjLhzXV0DoW0wseD22C12Ce/       Bs6tApl9nLuuCcoOqL75lZKc7lmiojFxTKeTIn8SjCXCjxmJYrlFLCk6m0VcqfkW0ERzgyY0pmEsH2Ry2+oPEoxjbBLlZQS3T7ghKpzwuQW5GJfLAs2RSR/       9n3PZnOXyz9a6uWEmiCwAqXNEqiTKOEkfW0/+Fm1RBOtCN7+r+nmL+1S15JfNaM/PYYOTR9inxO0j4cCqJaxVsm2WOSSBktolexYXPdsvDnrP9/WXKTUP/nSwb+ilr6ZIAhSvA8GuMD2IMgjXUBuVVWFf4fIHMcCYld4SYYJYcQua/AHCxuI6XutQsQePw29i8ZokxQKNa8jIcGMin8dq00FYwK5kqjTc5tjP5sS8NykwkTEN4zq0Azd9wn2NsclzMGRutkww==",
       "expiresInSeconds": 3600
   }

  6. If you use the wrong credentials or haven't subscribed to the requested resources, you get an unsuccessful response with an error description.

    Response example in case of a wrong authorization token:

    Status code 401

    Body:

       {
       "error": "Unauthorized",
       "error_description": "Token Validation Failure - Unable to verify signature segment"
   }

    Response example in case you don't have permission to access resources:

    Status code 403

    Body:

       {
       "title": "Error accessing extsvc resource",
       "code": "E504014",
       "errorCause": "User {userId} does not have readResource permissions on extsvc resource   hrn:here-dev:extsvc::{​​​realm}​​​:{bucketName}-​​​{somePath}​​​",
       "action": "Verify user has policy/permissions granted via ExtSvc Marketplace   subscriptions",
       "errorTag": "extsvc_resource_forbidden"
   }

results matching ""

    No results matching ""