CoCalc API Tutorial - First Steps
1. Getting started
The steps below assume that you have a copy of the tutorial files in a CoCalc project and that you can modify files in that project. If you have not done so already, the quickest way to do that is to click this link to the "Public" shared folder for the tutorial, then click "Open with one Click!".
You will need internet access for the tutorial project. For this you need to apply a CoCalc license to your copy of the project, or apply the internet access upgrade if you have an upgrade plan.
2. Create your API key
NOTE: Your API key carries access privileges, just like your login and password. Keep it secret.
Most API requests require an API key for authentication. Create one now.
Log into your CoCalc account.
Open Account > Preferences and under
Account Settings, find the API item and clickReveal key.... Enter the account password at the prompt.
When your password is accepted, the dialog changes. Click
Create API Key.
Your new api key is displayed. Save it someplace secure. If you ever want to change your key or delete it, return to this dialog.
3. Create Credentials File for API User
During testing, it can be useful to keep credentials for the account under test in a file that is separate from shared projects and git repositories, so that it is not inadvertently shared. This project uses a folder SECRET in your project's home directory, and a file ~/SECRET/testuser.yaml for account credentials.
Take a moment now to create the ~/SECRET/ directory and manually enter the API key for your test account according to the following example:
4. API utility functions in Python
Before running example programs, take a moment to review the code in notebook PYTHON/01-utils.ipynb.
Run the cells in this notebook to make sure your setup is correct. There should be no error messages.
5. API example: get CoCalc account_id
Each CoCalc account has an account_id which is a UIUD string. This field is needed for some API operations, so let's find out the value for your account.
This example uses the query endpoint to get the account id for your account. This call cannot be used to get the account id for other users than the owner of the API key used on the call.
Open notebook PYTHON/02-get-my-account-id.ipynb. This notebook uses the utility functions defined previously.
Each API call has a payload. In the Python script, payload is provided as a dict. Then it is sent as a JSON object in the body of and HTTPS POST request.
The payload in this example is typical for a query get request:
We can break down the payload this way:
"query" - top-level attribute for query request
"accounts" - name of the table being queried
"account_id" - field in the table being queried
Specifying a value of None (which is translated to null in the JSON message) indicates that want to retrieve this attribute from the table.
Run the notebook now. Make a note of the account_id value returned for use in later examples in this tutorial.
Next Database Queries