Version 2023.10.20.001

Copyright and Proprietary Information Notice
© 2023 Synopsys, Inc. This Synopsys Cloud OpenLink Application Programming Interface (API) and all associated documentation are proprietary to Synopsys, Inc. and may only be used pursuant to the terms and conditions of a written agreement with Synopsys, Inc.

Disclaimer
Synopsys, Inc., and its licensors make no warranty of any kind, express or implied, with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.

Trademarks
Synopsys and certain Synopsys product names are trademarks of Synopsys, as set forth at https://www.synopsys.com/company/legal/trademarks-brands.html. All other product or company names may be trademarks of their respective owners.

Third-Party Links
Any links to third-party websites included in this document are for your convenience only. Synopsys does not endorse and is not responsible for such websites and their practices, including privacy practices, availability, and content.

This document describes the Synopsys Cloud OpenLink API which enables semiconductor foundries and EDA and IP vendors to interoperate on a system-to-system level with the Synopsys Cloud. Specifically, vendors can provide information about their product entitlements for a Synopsys Cloud customer. The customer can request licenses from the vendor using the API. The licenses are then installed in Synopsys Cloud. The scope of this document covers the following Synopsys Cloud OpenLink API functionality:

• Vendor Entitlements: The third-party vendor provides a list of available license entitlements for a specific customer to the Synopsys Cloud
• Vendor License Request: The third-party vendor provides license files for installation in the Synopsys Cloud for use by the specific customer

High Level Flow

• A Synopsys Cloud customer navigates to a "Third-Party Entitlements" page in the Synopsys Cloud portal UI
• The customer chooses a vendor for which they want to browse entitlements and eventually request licenses
• Synopsys Cloud fetches the available entitlements for the customer through the vendor entitlement API endpoint
• The vendor API response lists the available entitlements which are presented by the UI
• The customer selects the quantity of entitlements for which they want to request a license and submits the request
• Synopsys Cloud invokes the vendor license API endpoint
• The vendor provides the license files in response which are installed on the Synopsys Cloud license server

The graphic here illustrates the licensing flow.

Basic Synopsys Cloud OpenLink API Sequence Chart

The sequence chart diagram in this section shows the basics of the following flows.

• OAUTH2 based authentication (OAUTH2 and API Key is supported)
• Retrieve entitlements
• Configure licenses requests
• Request licenses

Synopsys Cloud OpenLink API Details

The API for integration with Synopsys Cloud is specified using the OpenAPI v3 standard. The specification contains all details needed to implement the API . This section provides additional information to clarify the specification .

• The specification can be viewed using the online Swagger Editor tool
• The online Swagger Editor tool can also be used to autogenerate a working reference server and/or client, in any programming language (NodeJs, Java, Python, Ruby etc.), as a cloud service

Synopsys Cloud OpenLink API Fundamentals

This section provides common properties of the Synopsys Cloud OpenLink API.

• Only secure data transfer with https and TLS 2.0 or higher over https is supported.
• Only Content-Type: application/json is supported for requests.
• OAUTH2 and API key-based authentication is supported.
• The UI never issues requests from the customer's device directly to the vendor. All requests to the vendor endpoints are initiated from a service secured in the Synopsys Cloud service layer from a defined network.
• The UI never retrieves any vendor API information. All vendor API information such as URL, authentication method, authentication URL, and API key are only handled inside the Synopsys Cloud service layer and never sent or exposed in any form to the UI on the customer' s client device.

Vendor API Onboarding for Synopsys Cloud OpenLink

Each vendor registers the entitlement API with Synopsys Cloud through a manual onboarding flow. Customer specific details to be used for customer identification at the vendor side are agreed on and stored in the Synopsys Cloud for the customer.

The following table summarizes the kind of information needed for onboarding.

The vendor API onboarding information is registered according to the following schema. For simplicity, information discussed further in this section is wrapped via <>

See Swagger OpenAPI specification for VendorApiRegistration

    {
            "auth":"OAUTH2",
            "oAuthApi":<vendorAuthApi>,
            "entitlementApi":<vendorEntitlementApi>,
            "customerIdentification":{
                "params":<vendorCustomerFields>
            }
    }

The API endpoint for the license generation is dynamically provided with the entitlement query result. This allows the vendor to provide different endpoints for different licenses. The following sections provides more details about the specific properties of the vendor information registered in the Synopsys Cloud

Onboarding Information - Customer Identification Properties

The customer will be identifiable by the vendor through the D-U-N-S (a unique nine-digit identifier for businesses) number. In addition, the vendor can specify additional parameters to be provided by the customer through the Synopsys Cloud to the vendor.

In the onboarding VendorApiRegistration schema, the customer identification property customerIdentification allows the vendor`` to define optional customer fields which are to be provided with the API calls from the Synopsys Cloudto thevendor`.

See Swagger OpenAPI specification for VendorCustomerInfo

An example for optional customer fields is given below. Here, the vendor is asking the customer to provide a string mandatory parameter siteId.

        ...
        "customerIdentification":{
                "params":[
                    {
                        "title":"Site Id",
                        "key":"siteId",
                        "type":"String",
                        "required":true
                    }
                    ...
                ]
            }

The values specified in the above required parameters are then provided under the property vendorCustomerIdentification along with the API requests for entitlements and license retrieval.

Onboarding Information – Vendor Entitlements API

The entitlement API is a static URL that needs to be provided during onboarding. The further API information for retrieving the licenses are provided dynamically using the entitlement API.

{
    
    "url": "https://api.vendor.com/v1/synopsys/get-entitlements",
    "header": {
      "my-extra-info":"anything"
    },
    "staticbody": {
      "my-extra-info":"anything"
    }
}

The properties defined under staticBody are merged into the body of the POST request for the entitlement.

Onboarding Information – Vender License Request API Key Based Authentication

For API key based authentication, the vendor must provide a header and value for the API key

See Swagger OpenAPI specification for ApiKeyAuthInfo

An example for the onboarding information needed for ApiKeyAuthInfo is shown below:

 {
    "header":"x-api-key",
    "value":"9114dd77-912e-4179-a8c5-0a8de9dd44cc"
 }

The Synopsys Cloud initiating service provides the API key in the header with each request for the entitlement API and the license generation API as shown in the following example:

 {
    "headers": { "x-api-key":"9114dd77-912e-4179-a8c5-0a8de9dd44cc" }
 }

Onboarding Information - OAuth2.0 Based Authentication

For two legged OAuth2.0 based authentication according to RFC 6749 the authentication URL, client ID and client secret are required from the vendor for API onboarding. It is possible to augment those parameters with additional static parameters which will be merged into the POST request body.

See Swagger OpenAPI specification for Oauth2ClientInfo

An example for the onboarding information needed for Oauth2ClientInfo is shown here:

{
  "url": "https://vendor.com/api/oauth2/token",
  "header": {
    "x-my-header": "xyz"
  },
  "staticBody": {
    "origin": "synopsys"
  },
  "clientId": "6779ef20e75817b79602",
  "clientSecret": "dl9aUnVyOWdtQ3gxTTlobGU5N2ZWQUd5amdCcUsya2hWdVlMZmZOLWVOZw=="
}

Vendor Entitlement API

The entitlement API allows the Synopsys Cloud to retrieve the available entitlements from the vendor for a specific customer.

Vendor Entitlement API - Request

A POST request will be made from Synopsys Cloud with the following values encoded as body parameters:

SWAGGER: Please see Swagger OpenAPI specification for EntitlementsRequestDto:

{
    "customer": {
      "name": "Big Chip Semi",
      "dunsNumber": "1232234345",
      "synopsysCustomerId": "5a8649c7-129e-447b-afb2-77b778e66ac3",
      "vendorCustomerIdentification":{
        "sideId": "32668"
      }
    }
} 

This information is used by the vendor to identify the customer. The vendorCustomerIdentification properties are registered at the Synopsys Cloud during the vendor API onboarding process.

Vendor Entitlement API - Response

Once invoked from the Synopsys Cloud, the entitlements API needs to respond according to the following schema:

SWAGGER: Please see OpenAPI Swagger specification for EntitlementsResponse

{
    "customer": { }, // Same as in the request dto
    "provides":[ ]   // Array with entitlement information, See under "Item Type" for possible values
}

The details of the possible contents that the array provides are described in the next section. If all the licenses can be provided by the same endpoint from the vendor, then the array may only have one entry. Each entry lists all entitlements for which licenses can be retrieved through a single license retrieval endpoint. In case different endpoints are needed, multiple items can be provided with different endpoint configurations.

Item Type – License Entitlement

This item type is used by the vendor to expose all license entitlements and allow the Synopsys Cloud customer to request licenses.

• Licenses are automatically installed on the customer's license server in the Synopsys Cloud.
• Licenses can be provided as one or more files by the vendor
• The license file can be provided either synchronously or asynchronously by the vendor in the subsequent endpoint for license retrieval.

SWAGGER: Please see OpenAPI Swagger specification for LicenseEntitlements

An example for the LicenseEntitlements item as part of EntitlementsResponse provides array is shown here.

{
    "customer": {
      "name": "Big Chip Semi",
      "dunsNumber": "1232234345",
      "synopsysCustomerId": "5a8649c7-129e-447b-afb2-77b778e66ac3",
      "vendorCustomerIdentification":{
        "sideId": "32668"
      }
    },
    "provides": [
          {
            
            "title": "AutoChip EDA Tools",
            "description": "Digital Design EDA Tools Licenses",
            "kind": "ProvideLicense",
            "licenseEntitlements": [
                {
                    "title": "Power Analyzer",
                    "aux":{"part": "part-1234"},
                    "qtyMax":10,
                    "termEndDate": "2024-08-01T00:00:00.000Z"
                },
                {
                    "title": "Timing Analyzer",
                    "aux":{"part": "part-5678"},
                    "qtyMax":5,
                    "termEndDate": "2025-08-01T00:00:00.000Z"
                }
            ],
            "licenseRequestApi":{
                "url": "localhost:2000/get-license",
                "header": {
                    "x-my-header": "xyz"
                },
                "staticBody": {
                    "origin": "synopsys"
                },
            },
        } 
    ]
}

Each entitlement item must contain the following:

• A title
• Optionally a description, maximum available quantity qtyMax, end date for the license term termEndDate
• Optionally any auxiliary information to identify the entitlement with the license request under the property aux.

For the license request, the title and aux object is provided along with the requested quantity qtyMax to the vendor license generation endpoint.

Vendor License Request API

After configuration of the requested quantity in the UI, the vendor endpoint to request licenses is invoked from the Synopsys Cloud. In response to the request, the vendor provides the requested licenses or returns an error.

• It is possible to send multiple license files by the vendor if needed. Each license file can be provided back to the Synopsys Cloud synchronously or asynchronously (polling) from the vendor.
• A synchronous response method should be used if license generation takes less than 20 seconds
• An asynchronous response method should be used if license generation takes more than 20 seconds

SWAGGER: Please see OpenAPI Swagger specification for ProvideLicenseRequestDto

An example for a ProvideLicenseRequestDto item to request licenses from the vendor is provided here:

{
  "customer": {
      "name": "Big Chip Semi",
      "dunsNumber": "1232234345",
      "synopsysCustomerId": "5a8649c7-129e-447b-afb2-77b778e66ac3",
      "vendorCustomerIdentification":{
        "sideId": "32668"
      }
  },
  "licenseRequests": [
    {
      "title": "Power Analyzer",
      "aux":{"part": "part-1234"},
      "qty": 2
    },
    {
      "title": "Timing Analyzer",
      "aux":{"part": "part-5678"},
      "qty": 3
    }
  ],
  "host": {
    "id": "id-auto-filled-by-snps",
    "name": "auto-filled-by-snps"
  },
  "origin": "synopsys",
}

Response - License File Generation

The response of the licenses request endpoint can provide the license file synchronously as part of the response, or asynchronously through a download URL which gets polled.

SWAGGER: Please see Swagger Type ProvideLicenseResponse

Synchronous Response - License File Generation

The synchronous response provides the license file(s) directly as part of the HTTP POST response body. This response type is used if the license file can be provisioned in less than 20 seconds, thereby avoiding HTTP timeouts

The synchronous response is indicated by the property downloadType set to "Sync" in the payload. The property data can accommodate data along with filename and type for one or more licenses. In case of a license, the property fileType must be set to "License" as shown in the example below:

{
 
  "files": [
    {
      "fileName": "lic_vendor_tool.lic",
      "fileType": "License",
      "data": "<Buffer 48 61 6c 6c 6f>",
      "downloadType": "Sync"
    }
  ]
}

The file property data contains the Base64 encoded license file as a buffer. See below an example for Base64 encoding in plain JavaScript

    const licenseString = 'SERVER enterp ...';
    const buff = new Buffer(licenseString);
    const data = buff.toString('base64');

Asynchronous Response - License File Generation

The asynchronous response does not provide the license file(s) directly as part of the HTTP POST response.

Instead, the response provides URLs where license file(s) can be downloaded after a time specified by the vendor in the response. This response type shall be used if the provisioning of the license file cannot be done in less than 20 seconds to prevent HTTP timeouts. The diagram below illustrates the interaction model:

The asynchronous response is indicated by the property fileType set to "Async" in the payload. In the array data, for each license, the instructions for the license file download are given (instead of the license file data) as shown in the example.

{
 
  "files": [
    {
      "fileType": "Async",
      "fileName": "lic_vendor_tool.lic",
      "downloadType": "License",
      "downloadApi":{
        "url": "http://vendor.com/download?uuid=eec85dab-6de8-4f1f-8234-6df676bdb834",
        "headers": {
          "x-my-header": "xyz"
        },
        "staticBody": {
          "origin": "synopsys"
        },
        "pollStartDateTime": "2023-07-12T09:40:18.000Z",
        "pollIntervalSec": 30
      }
    }
  ]
}

The property url provides the URL for the download along with the method, optional headers, and optional body parameters under staticBody. The ISO Date string property pollStartDateTime indicates when Synopsys should attempt a download and the suggested poll interval using pollIntervalSec. If the file is not yet available, a 404 response is returned.

Error Response

In case the validation of parameters as inputs to the REST API fails, each endpoint should return an error with the status code 400 as shown below:

{
  "code": "LICGEN001",
  "message": "License generation failed",
  "statusCode": 400,
  "tid": "eec85dab-6de8-4f1f-8234-6df676bdb834",
  "errors": [
    {
      "message": "LmHostId is missing but required"
    }
  ]
}

The property code allows the encoding of a vendor specific error code. The message contains information about the error to be provided back to the customer. The optional property tid allows the insertion of a vendor server trace ID for tracing and debugging. This is especially useful for 500 internal server errors. The optional array errors can contain additional error information (e.g., specific errors for individual parameters).

Sample Implementation (NodeJs)

The following code shows a simple but functional example implementation for the Synopsys® Cloud OpenLink API Specification using NodeJS in Javascript.

/**
 * NodeJS example application of the Synopsys® Cloud  OpenLink API Specification
 *
 * npm install express
 * npm install body-parser
 * node main.js
 * 
*/


const express    = require('express')
const bodyParser = require('body-parser')
const app = express()

/*
 * Server settings
 */
const port = 2000
const host = 'localhost'
const protocol='http'


app.use(bodyParser.json())

// Some tracing...
app.use((req,res,next)=>{
    console.log(`TRACE: ${req.method} ${req.url}`)
    next();
})


/**
 * Example implementation for get-license API
 */

app.use('/vendor-api/get-license', async (req, res) => {

    // Vendor sample endpoint to generate a license with synchronous response 
    console.log(req.body)
    const customer = req.body.customer
    const hostId = req.body.host.id;
    const hostName = req.body.host.name;

    let response = {
        files: []
    }

    const backOfficeLicenseGeneration=async ()=>{
        return "DUMMY LICENSE FILE...."
    }

    /* Here, we generate a license per part as one possible option */
    for (let licenseRequest of req.body.licenseRequests) {
        /* Vendor's backoffice call to generate license*/
        const licenseFile = await backOfficeLicenseGeneration(customer, hostName, hostId, licenseRequest.qty, licenseRequest.expiry, licenseRequest.aux.part)

        response.files.push({

            files: [{
                fileType: "Sync",
                data: Buffer.from(licenseFile, 'base64'),
                fileName: `lic ${hostId}.txt`,
                downloadType: "License"
            }
            ]
        })
    }

    /* Respond to Synopsys with generated licenses */
    res.json(response)

})

/**
 * Example implementation for get-entitlements API
 */

app.post('/vendor-api/get-entitlements', (req, res) => {

    /* Vendor sample endpoint to query entitlements and map user options to vendor's get-license API spec */

    const response = {

        "customer": req.body?.customer,
        "provides": [
            {
                
                "title": "AutoChip EDA Tools",
                "description": "Digital Design EDA Tools Licenses",
                "kind": "ProvideLicense",
                "licenseEntitlements": [
                    {
                        "title": "Power Analyzer",
                        "aux":{"part": "part-1234"},
                        "qtyMax":10,
                        "termEndDate": "2024-08-01T00:00:00.000Z"
                    },
                    {
                        "title": "Timing Analyzer",
                        "aux":{"part": "part-5678"},
                        "qtyMax":5,
                        "termEndDate": "2025-08-01T00:00:00.000Z"
                    }
                ],
                "licenseRequestApi":{
                    "url":`${protocol}://${host}:${port}/vendor-api/get-license`,
                    "header": {
                        "x-my-header": "xyz"
                    },
                    "staticBody": {
                        "origin": "synopsys"
                    },
                },
            } 
        ]
    }


    res.json(response)
})



app.listen(port, () => {
    console.log(`Example Synopsys® Cloud OpenLink API vendor server listening on port ${port}`)
})