CoCalc Public FilesPublic / FirstSteps.mdOpen with one click!
Author: Hal Snyder
Views : 401
Description: API tutorial part 1
Compute Environment: Ubuntu 18.04 (Deprecated)

CoCalc API Tutorial - First Steps

1. Copy programs from this tutorial into your work area

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.

2. Setup your CoCalc account

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

  • first name
  • last name
  • email address
  • password

3. Ping the API service

Open sample program PYTHON/00-ping.ipynb and run all the cells. You don't need an API key to run this example.

4. 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 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.

5. 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 and a file ../SECRET/testuser.yaml 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.

6. API utility functions in Python

Before running more example programs, take a moment to review the definitions of load_user_info() and 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:

%run ./01-util.ipynb

Add a second cell and invoke call_api() without explicit arguments. You should see a successful 'pong' result, just as with the previous example.

7. Find your 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 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:

{"query":{"accounts":{"account_id":None}}}

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. 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:    ...

Navigate