In order to run the example programs in this tutorial, you will need to copy them into a CoCalc project of yours or other system that can run Jupyter notebooks and access https://cocalc.com. Note that API calls from a CoCalc project will not work unless you upgrade your project to have internet access.
If you're viewing this file from the shared project, you can click the folder icon at upper left to open the Files listing, select one or more files, and download to your local computer or copy to a CoCalc project.
If you're viewing this file from a git repository, you can clone it to your local computer or to a CoCalc project.
We'll assume you're working with a writable copy of the tutorial in what follows.
You'll need a CoCalc account to use the API. If you don't have one, go to https://cocalc.com and create an account now. Make a note of values you entered for
Open sample program PYTHON/00-ping.ipynb and run all the cells. You don't need an API key to run this example.
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 click
Reveal 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.
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 and a file
for account credentials.
Take a moment now to create the
../SECRET/ directory and manually enter credentials for your test account according to the following example:
user info for API test api_user: first_name: ... last_name: ... password: ... # optional for now api_key: ...
First and last name are not used in the examples, but may be
helpful when testing with multiple accounts.
You can leave out
password for now if you like, and only add when
running API examples that call for it.
Before running more example programs, take a moment to review
the definitions of
call_api() in notebook PYTHON/01-utils.ipynb.
Create a new Jupyter notebook in the same PYTHON folder and put the following in the first cell:
Add a second cell and invoke
call_api() without explicit arguments. You should see a successful 'pong' result, just as with the previous example.
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 the current account.
The next 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 (other than ping) 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:
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. Add the account_id value returned to
a new line in the
../SECRET/testuser.yaml file for later use:
user info for API test api_user: ... account_id: ...