Skip to content
API Cloud

Migrating to API Cloud v2.0 FAQs

The following Frequently Asked Questions (FAQs) pertaining to migrating from API cloud v1.0 to v2.0 and answers are provided.

I have published APIs in API Cloud v1. When do I need to migrate my APIs to API Cloud v2?

You need to migrate your APIs/proxies before August 30, 2021. After then, API Cloud v1 will be discontinued and you will no longer have the opportunity to migrate from v1 to v2. API Providers with exceptions must complete their migrations before Dec 31 2021.

No self-migration is offered for the Distributed Gateway or the Azure Gateway at this time. API Providers will need to work with integrators to update their endpoints.

I have published APIs in API Cloud v1. What will happen if I don’t migrate my APIs to API Cloud v2?

If you decide not to migrate your APIs/proxies from v1 to v2, your subscribers will no longer be able to consume them after August 30th, 2021. Providers with exceptions have until Dec 31 2021 to complete their migration.

** I have published APIs in API Cloud v1. What changes do I have to do in my APIs as part of the migration process to APICloud v2?**

APICloud v2 supports both access tokens V3 and V4 till August 30th. The API Providers have to make the changes to make sure that their APIs are compatible with JWT 1.0 (JWT from V3 access token) and JWT 2.0 (JWT from V4 access token). As the V3 token endpoint wouldn’t be there after August 30th, it is important to support both of the JWT types in the Backend APIs/Target Servers, so that the consumers of your apis would not have any impact after August 30th.

** have published APIs in the Distributed (AWS) Gateway or Azure Gateway of API Cloud v1, Would that have any impact after August 30th?**

Yes, Distributed and Azure Gateways validate the token against v3 identity system and v3 endpoints would not be available after August 30th, The API Providers should migrate their application from [TID Trimble Identity - see identity** v3 to TID v4 and make the relevant changes in the Backend APIs to handle the new JWT claims, and migrate their APIs to API Cloud v2 by creating a new version of the APIs. Providers with exceptions have until Dec 31 2021 to complete their migration.

** My application consumes endpoints from API Cloud v1. Will I need to consume different endpoints?**

Yes. All the APIs offered in API Cloud v1 will have new endpoints in API Cloud v2 after their migration. Your application consuming the v1 endpoints will eventually have to be updated to consume the new v2 endpoints. API Providers using the Default Gateway will be able to maintain their legacy consumption URLs for at least 6 months after August 30th. For the Distributed and Azure Gateways, applications will need to consume different endpoints once they are available.

** My application consumes endpoints from API Cloud v1. Do I need to wait for the APIs I subscribed to migrate to API Cloud v2 before I can migrate my own application to v2?**

No. You can migrate your consuming application at your own pace. You don’t have to worry about the migration timeline of the API it consumes.

What is a “namespace” in the API Cloud v2 proxies?

Namespace is a logical grouping for a series of related proxies you want to create. It will be part of the URL of your proxy’s endpoint. Proxies’ endpoints look like the following: https://cloud.{env}.api.trimblecloud.com/{namespace}/{proxy-name}/{version}

where:

  • {env} is the environment

  • {namespace} is your software application product

  • {proxy-name} is the name of your proxy

  • {version} is the version of your proxy

Example: https://cloud.dev.api.trimblecloud.com/alk/routereport/1.0

You can have as many Namespaces as you need for your team. Other teams don’t see them. For more information, see Proxies and Namespaces.

I use a shared email account to manage my APIs and applications in API Cloud v1. Can I use this shared account in the API Cloud v2 console?

No. You should only use your personal TID account to manage your proxies, API Products, and applications in API Cloud v2. Shared accounts do not support [MFA Multi-factor authentication (MFA) provides a method to verify a user’s identity by requiring them to provide more than one piece of identifying information. This ensures that only valid users can access their accounts.**, you won’t be able to log into API Cloud v2 using them.

I use a shared email account to manage my APIs and Applications in API Cloud v1. How can I initiate a migration from APICloud v1 to APICloud v2?

Use the following to initiate migration from APICloud v1 to APICloud v2:

  • Invite the shared account user as a member of your Team in APICloud v2.

  • Initiate the API/Application migration from APICloud v1 as a shared account user.

  • After the successful migration, the APIs/Applications of the service account user will be mapped to your Team in APICloud v2.

  • Manage the migrated entities by logging into APICloud v2 by your TID v4 user credentials.

I have registered my application in API Cloud v1. I have migrated the Application from v3 to v4 from APICloud v1, Do I have both of the keys (v3, v4) in API Cloud v2?

Yes, Both of the keys will be carried over to APICloud v2, but the Cloud Console UI would show only the v4 keys.

What are the current limitations of API Cloud v2?

API Cloud v2 is an MVP Release and will continue to grow and evolve with your feedback. A few limitations or implications shared by our users are listed below for consideration:

  • Team name cannot be edited.

  • Namespaces cannot be renamed.

  • Namespaces cannot be deleted. Workaround: None, think about it twice when creating a namespace.

  • Subscribing to an API Product does not require approval from the publisher. Workaround: None. Please contact the publisher to understand the terms of usage of the API. Request/Approval workflows will be added to API Cloud v2 within the Trimble Developer Marketplace update.

** Is API Cloud v2 compatible with TID v3? If a user is not able to migrate to TID v4 but they have successfully migrated to API Cloud v2, will this setup work?**

Yes, API Cloud v2 is compatible with TID v3 until August 30th. When the user initiates the API Cloud v2 migration, all of the APIs, Applications (TID v3) and its Subscriptions would be migrated to API Cloud v2, so that there won’t be any issues with the API consumption workflow. The migrated Applications (TID v3) would only be available in the Trimble Developer Marketplace.

** I have published my API as a Private endpoint (linked through VPC Peering) in API Cloud v1, but API Cloud v2 expects the endpoint should be publicly accessible. How can I protect my Public endpoint from the external world?**

API Cloud v2 supports only Public endpoints, but you can add the Gateway’s exit IP in your allowed list to ensure that the traffic is coming from API Gateway. Please fill the form in this link to get the exit IPs of gateway in APICloud v2 In addition to this, you can add the custom rules in your WAF to add more security.

** How do you modify the Threat Detection Template for an API?**

The following steps can help you modify the threat detection template.

  1. Start by subscribing to the API Cloud Management API in the Cloud Console.
  2. Download the template for threat detection by making a GET call with the template Name: AdvanceUser_ThreatDetectionTemplate.
  3. Configure your Jenkins jobs/CICD pipelines with the given pipeline script that deploys your proxy in the Cloud Console.

Example Request:

curl
    --request GET 'https://cloud.api.trimble.com/proxy-management/publisher/api/template/AdvanceUser_ThreatDetectionTemplate'
    --header 'Authorization: Bearer eyJ0eX...'
    --output threat_template.zip

TLS 1.2 FAQs

** Why are TLS 1.0 and 1.1 are not supported in API Cloudv2?**

TLS 1.0 and 1.1 are out-of-date protocols that do not support modern cryptographic algorithms, and they contain security vulnerabilities that may be exploited by attackers. The Internet Engineering Task Force have formally deprecated both protocols. In addition, the vast majority of encrypted Internet traffic is now over TLS 1.2, which was introduced over a decade ago.

TLS 1.0 and 1.1 will not be supported in API Cloud v2. If you are an API Provider deploying new API Proxies/Products in API Cloud v2, or if you are migrating existing APIs into API Cloud v2, you must ensure your API Backend is configured to support TLS 1.2.

Will this affect my users that have up-to-date devices?

It should not, because the vast majority of websites support TLS 1.2 and most browsers have already been updated. According to Qualys’s SSL Labs, 99.4% of websites support TLS 1.2 as of April 2021.

Who is impacted by the TLS 1.2 Change?

View this report to find APIs and API Providers by User/Email to see if you or your APIs are impacted: APIs and Users at Risk for Weak Ciphers (TLS 1.0/1.1)

What is the impact?

Calls made to APICloud v2 will fail if earlier versions of TLS 1.2 are used. The “OpenSSL SSL_connect: SSL_ERROR_SYSCALL” error is returned.

: What do I need to do to fix this issue?

Upgrade/enable TLS 1.2 if your server does not support it. Upgrade your ssl library to support TLS 1.2.

Assuming you are using Linux and Apache for TLS connection management, you can update the SSL configuration by modifying this line to add “+TLSv1.2 ”:

  • SSLProtocol -all +TLSv1 +TLSv1.1 +TLSv1.2 (Sidenote: Since they are not really supported anywhere anymore, it makes sense to also remove the 1.0 and 1.1 settings while you are in here.)

  • That config is typically located in /etc/httpd/conf.d/ssl.conf

  • Restart Apache and you are good to go.

  • Restart httpd service.

If you are using Nginx, you will want to modify this line in a similar way:

  • ssl_protocols TLSv1 TLSv1.1 TLSv1.2; This config is typically located in /etc/nginx/conf.d/

  • Restart Nginx and you are good to go.

  • Restart httpd service.

If you run into any error messages with the restart, you may have an out-dated SSL library. Make sure you are using at least openssl v1.0.1g.