Developer Guide
Figure 1: Overview
Background Information:
Requesting a developer API key
DataBC offers an API gateway for use with APIs owned and managed by the Province of BC. Various services are available for different users. For example, users include DataBC system administrators, BC Government API owners, and developers.
Developers with a GitHub account can manage, request and replace API keys through a web interface. Specifically the web application is called the Developer API key app.
If you wish to begin using this application, follow the instructions below.
For APIs that require a key, and where approved by API owners, the Province of B.C. enables access to developer API keys. Keys are unique to each individual developer and provide the ability to make up to 2 requests per second. API keys are non-transferable and can be replaced if you notice unauthorized use. If you experience any issues with your API key please contact [email protected].
Developer API keys are designed to support exploration and the development of scripts and applications. If you are building an application for the Province of B.C. you can use your developer API key for testing and development. Once the application code is delivered to the Province of B.C. the respective Ministry will begin to make use of their own production API key granted to the API(s).
The Province of BC is using GitHub (github.com/bcgov) to store API specifications and supporting documentation. Although we provide the main details on all APIs in the BC Data Catalogue we also use GitHub for more technical information and hosting code. Specific to code we also use GitHub when releasing code under an open license.
The Province of BC is also using GitHub for issue tracking and project boards.
BCDC is an online application that helps users to find, understand and explore APIs, Data and Applications. The catalogue also provides contact information so that data users can contact Data Custodians for additional information if required.
Data, APIs and Applications registered and presented through the BC Data Catalogue are managed by Data Custodians from across the broader public service. The Data Custodial Organizations are visible under the Organizations tab.
DataBC manages the BC Data Catalogue software and infrastructure, and delivers user training and authorization management.
To request developer API keys you require a GitHub account. To create a free GitHub account, follow the instructions at github.com/join.
To register with the API Gateway you simply need to join the bcgov-keygen GitHub organization. You can do this by clicking the 'Get API Key' button in an API console within BCDC, and then providing your GitHub ID. Alternatively, you can join by visiting the Developer API Key app and clicking the 'Request Access' button.
Figure 2: Application interface
You will receive an email immediately requesting you to confirm the authorization.
Once you have authorized GWA, you will see the API keys page. You will also see your GitHub ID on the top right of the screen next to the log out button.
Review the Terms of Use and check to box to activate the ability to generate developer API keys.
After clicking on ‘Create API Key’ you will see your API key(s) at the top of the screen which has access granted to the APIs listed under 'Applications'.
Figure 3: Developer API key app
If you need to replace your API key with a new one, you can click on ‘Replace API Key’.
Navigate to the BC Data Catalogue at the URL below or through the DataBC homepage and discover an API. You can search for an API using a keyword search or by filtering on the ‘Web Service / API’ dataset type. You may also search by using the 'OpenAPI spec' tag to find metadata records containing API consoles.
Once you find an API, click on the title to open the metadata record.
https://catalogue.data.gov.bc.ca/
Within the ‘Data and Resources’ section of the API metadata record click on ‘API Console’. The API console will allow you to test the API, explore its resources and parameters. You can also use the 'Server' drop-down list to select an environment to test against including delivery, test and production (figure 5).
Figure 4: Data and Resources list
Not all APIs require keys, however, those that do will require you to provide one. You can provide a key automatically by clicking 'Get API Key' and entering your GitHub credentials. You can also manually enter a key by clicking 'Enter API Key'.
If you wish to create or delete API keys or review a list of APIs that are available to you click on 'Manage API Keys'.
The 'API Key Help' button will take you to this Developer Guide page.
Figure 5: Get API Key
In some cases, API owners allow all developers to have access by default. These APIs will automatically be listed for you in the 'Applications' section of the Developer API Key app. If the API owner wishes to grant access to individual developers you will need to send the API owner an email. If this is the case, within the API metadata record (BCDC) scroll down to the 'Additional Information' section of the API metadata record. Send an email to the contact listed to request access to the API. You will need to include your GitHub account name and the API name in the email.
Once you have confirmed that the API owner contacted step 3 has provided you with access you can click the 'Get API key' button shown in the figure above. You may be asked to log in with your GitHub account if you have not already as well as to authorize the use of your API key.
By default, developer API keys expire after 90 days. GWA will create a new API key for you prior to this expiry and list it in your API key list. The age of each API key is shown next to each key in GWA. You do not need to request API access again, simply adopt the new API key.
Figure 6: Authorize API Console
You are now able to test the API using an API console and start developing your application.