More clear and concise API help documentation for Python

[matthew_mcvay]

The documentation on using rest-API calls with Upchain is not very helpful to someone like me who is very familiar with Python and wants to use it for these calls but is new to API calls.  The process is laid out over several pages and is not very easy to follow.  It is also geared towards the HTML programming language, although Python and windows command prompts can also be used.  None of the example scripts are written in Python.  I would like to see a single page that would list out step-by-step instructions for both completing the entire process of getting set up for API calls AND making your first calls in Python.  For example, "Step 1: create a server-to-server application, and here's how.  Step 2, ask Autodesk support to whitelist your client ID, and here's where you can find the information they need and how to submit that request.  Step 3, use an API call to obtain an authorization token, and here are some examples of how you can do that in Python along with the exact URL's needing to be referenced in the call.  This is the format in which the call needs to be made, and here is an example script you can use by filling in these values.  Step 4, use that authorization token to make API calls that perform other actions, and here is an example in Python of how you can do that.  Now that you know the 'how', here is the page for Swagger which gives a full list of the functions you can perform with Upchain's API and how to perform those functions.  Trying to piece together the necessary information from several different websites and pages is exhausting.

[PualQuek]

Hi @matthew_mcvay,

Our API docs are language-agnostic. It might be possible to have a swagger plugin that allows the user to select a programming language, and then it generates a code example to call that specific API in the selected language.

As a workaround, we suggest the following:

1. You can copy the curl command from the current help pages or from swagger, e.g. : https://help.autodesk.com/view/UPCHN/ENU/?guid=UC-API-FIRST-API-CALL

   curl --location 'https://live.upchain.net/api/project/v1/public_projects' \ 
   --header 'Authorization: Bearer \<your access token\>' \ 
   --header 'upc-selected-company: \<companyID\>' \ 
   --header 'X-User-Id: \<authorized email\>'

2. Import the curl command into a tool Like Postman:
3. Once you have the request imported into Postman - fill in the parameters
   1. (Upc-Selected-Company, Authorization header, X-User-Id, other request parameters).
   2. Test if it's working.
4. On the right-hand side of Postman, there is an option called "Code", selected that.
5. Choose "Python - Requests" or "Python - http.client", depending on preference (there are other 30 or so different programming languages to choose from).

A code example will immediately be generated, e.g.:

import requests

url = "https://live.upchain.net/api/project/v1/public_projects"

payload = {}
headers = {
  'Authorization': 'Bearer abc',
  'upc-selected-company': '123',
  'X-User-Id': 'my_user@company.com'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Regards,
Paul
Principal  User Experience Designer (Upchain)  

[matthew_mcvay]

Hi @PualQuek ,

Thank you for the help.  Since the time of the original posting, I have noticed a few inconsistencies in the documentation.  At the top of the Swagger page, it reads "To obtain companyId, first make a call to /api/auth/v1/companies endpoint" ( Swagger  ).  However, in the Upchain API Documentation , it reads "Note: Your company ID (tenant ID) will be provided to you once your tenant has been whitelisted."  It used to read "

Note: You may obtain the company ID (tenant ID) using the API: GET /api/auth/v1/companies" on July 18th, which was consistent with the Swagger page.  On July 18th, I was able to make an API call to that /companies endpoint to obtain my companyID, but it no longer works, giving me a 403 error.  I was told by the support staff that the only way to access that endpoint without the companyID is with a 3-legged token due to an "allow listing filter on Oxygen"; however, Upchain API does not support 3-legged tokens because it only supports server-to-server apps (Upchain documentation ) which don't use 3-legged tokens, per Autodesk API documentation , which talks about using POST tokens after making a GET Authorize call which requires a callback_uri which only applies to web apps.  It also appears that not all of the support staff know that they are supposed to include the companyID when they send an email confirmation that the tenant has been whitelisted.

1) Because the process seemed to be working just fine in July, why not revert back to that process by removing the "allow listing filter on Oxygen" for the /companies endpoint and changing the Upchain API documentation to be consistent with the Swagger documentation?

2)  Because Upchain only supports server-to-server apps, on the Swagger page, why not remove the first two authorization methods and just leave the "Oxygen (OAuth2, clientCredentials)" which applies to server-to-server apps?

3) From using the Swagger page and from the note on the aforementioned Upchain API Documentation , it appears that the companyID and tenantID are the same thing (I enter the same number for both to execute the calls on the Swagger page) - because the tenantID seems to be redundant, why not just remove the "tenantID" field entirely from the API process?

[PualQuek]

Thanks @matthew_mcvay for feedback.

I will coordinate with our Engineering team to address and resolve the matter.

Regards,
Paul
Principal  User Experience Designer (Upchain)