#**Understanding Public API Products**
###Understanding Public API Products
When an API product is set to Public visibility, it becomes accessible to external developers via the Developer Console. This allows third-party innovators to build applications using Trimble APIs, data, and services.
###Requesting Public Visibility for API Products
By default, all API products on the API Cloud console are set to Internal (restricted to your team/account/organization). If you need to expose your API to external developers, you must submit a request to the Trimble Platform Admin to update the visibility to Public.
###Pre-submission Guidelines
Publishers must review the below API Publisher readiness Guideliness and validate these items before submitting a ticket to the Platform Admin.
###API Publisher Readiness Guideliness Purpose: This outlines the mandatory requirements that must be met before initiating a request to the Platform Admin to make an API Product public. Completing these steps ensures technical stability, comprehensive documentation, and a seamless support experience for external developers. Review each phase below. Ensure all tasks are completed and verified by your team. Once finished, you may proceed with submitting your Public Visibility Request via the support portal.
| Task | Description | Resources / Reference |
|---|---|---|
| API Product Naming | API Product Name must follow consistent Trimble Product naming conventions (internal codenames are prohibited). The final name must be reviewed and approved by the Platform Team. | Example: Trimble Connect, Projectsight. DO NOT USE: Connect_V1, CCFS. |
| API URL Convention | The URL of a public API must adhere to the convention below: https://<region>.api.trimble.com/<basepath>/<version>The <region> is assigned for each deployment of the API based on its configuration, e.g. eu, us-east.The <basepath> is a kebab-case value derived from the product name, and identical to the project key used for public-facing documentation on Trimble Developer, e.g. connect. It may contain a kebab-case API name if an API product is not limited to one API and an OpenAPI definition file is provided for each API in the product, e.g. product/api-name.The <version> is the major version number of the API, prefixed with a lowercase v, e.g. v1.The URL, like the product name, must be approved by the platform team. | Example: |
| API Deployment & regional configuration | Verify that all APIs are successfully deployed to the Production environment and accurately mapped into the correct API Product. Additionally, ensure your API Product adopts the console’s recent regional deployment model. You must configure regional endpoints within a single API entity instead of duplicating the APIs for different regions. | [Link to API & Product Guide] [Link to Regional Deployment Guide] |
| Authentication Setup | The appropriate Application Types must be selected for the Product. Since Application Types determine the supported grant types (Authorization grant, Client credentials), choosing the correct ones is critical. If the required Application Type is not available or a custom type is needed, please submit the [Google form]. | [Link to Auth References] |
| Rate Limiting & Quotas | Verify that appropriate public usage plans (rate limits/quotas) are applied to prevent system threats by external applications. | [Link to API Configuration] |
| OAS & Linting | Ensure version-synced OpenAPI Specification is attached to each API within the product, and verify the spec passes the Trimble API Linting tool. | [Link to OAS & Linting Tool] |
| Create experience in your product based on Application Authorization | When an Application is authorized in the Admin console, it may be appropriate to create an experience in your product to allow for further configuration of the Application. For example, if the Application has a client credential grant type, then users in your product will need to be able to assign roles and permissions to that application in your product. | [Link to Guidance on managing application access after account level authorization] |
| Enforce application authorization | You need to modify your API so that applications created by external accounts (customers and partners) require application authorization before you return data. You should only return data for accounts in which the Application has been authorized. | [Link to Application Authorization Enforcement Guide] |
| Test your API Product | You must test all of the endpoints in your API product to ensure they return data as expected and properly enforce application authorization. | [Link to Steps to Consume API] |
| Developer Documentation | Documentation must be available on (or prepared for) developer.trimble.com, including a quick guide on how to perform an initial transaction with the API. | Contact: Noel Whelan [Link to GitHub] [wiki] |
| Developer Engagement and Support Intake Form | The Developer Engagement and Support Preparedness intake form must be completed. This form collects details on the developer support and escalation process, in addition to a commitment to engage with developers on the Network if prompted by Trimble Developer. | [Link to Intake Form] |
| Support escalation process | Define and document the developer support and escalation process with the Trimble Developer Team. | Contact: Noel Whelan |
| Trimble Marketplace Team Engagement | Do you plan to enable partners to publish applications for your API to the Trimble Marketplace? If yes, then have you been approved by the Trimble Marketplace team to be a part of the Trimble Marketplace Program? You must engage with the Marketplace Team to align on listing requirements. | Contact: Angie Wiering, Rachel Webster |
| Developer Sandbox Software | If your Product is intended to be used by Partner Developers then you should ensure that there is a Sandbox instance available for developers to use. - For multi-tenant SaaS applications, your sandbox software should be done through the Developer Console. - For single-tenant SaaS applications that require manual deployment, your software should be made available through the Marketplace Agreement. | [Link to Sandbox Implementation Guide] |
| Internal Charlie Post | (Post release) Publish a post on Charlie to announce the public availability of the API to the rest of the Trimble organization. | [Link to Charlie] |
| Developer Newsletter | (Post release) Keeping our developer community informed is essential for delivering a high quality platform experience. This ensures external developers are aware of your API releases, updates, and new features. To include your update in the official Trimble developer newsletter, complete the News and Updates Intake Form. This form helps the team to prepare announcements and ensures your content follows necessary submission guidelines. | [Link to News and Updates Intake Form] |
###How to Submit a Request
Public visibility is granted via a manual review process. To start, please send an email to cloudplatform_support@trimble.com with the following information:
- Business Justification: A brief explanation of why this product is moving to public visibility
- Submitting Team: The name of the team responsible for the product.
- Product Name: The exact name of the API Product as it appears in the Cloud Console.
- Application types selection: Specify if this is an End-user application (user signs in) or a Server-to-server app (Client credentials Grant) or anything else.
- Target Audience: Specify if the API Product is intended for Customer Developers/Partner Developers or both.
- Presubmission Review: Confirmation that the team has reviewed the API Publisher readiness Guideliness (Yes/No).
Important Considerations (Must Read) Before requesting public visibility, please review the following policy constraints. Once a product is marked as public, these conditions apply:
1. Irreversible Action - Once an API product has been moved to “Public” status, it cannot be reverted back to “Organization” level visibility. Settings are locked to maintain stability for external developers, but you may still add new application types. Ensure that the business case for public exposure is finalized before submitting the request. To request changes or for any queries, please contact Cloud support via cloudplatform_support@trimble.com. 2. Open Subscription Model - All public products are subject to Open Subscription. This means any external developer with access to the Developer Console can subscribe to and use the API Product without manual approval from your team. 3. Locked API Grouping - Once a product is marked as public, any APIs currently grouped or bundled within that product cannot be removed. Carefully review the list of API resources and endpoints included in the product before requesting the visibility change. However, you can add new APIs to a public product at any time.