API Registration Guide
Table of Contents:
- API Registration Generator application
- Getting access to ARGG
- Step 1: OpenAPI specification
- Step 2: General API information
- Step 3: API owner information
- Step 4: Metadata record
- Step 5: Access
- Step 6: API Gateway
The API Registration Generator (ARGG) provides a means to register an API with the BC Data Catalog and to optionally opt in to the DataBC API gateway. The API Gateway provides additional capabilities on top of an existing API.
To use ARGG you need to have an IDIR account.
Navigate to ARGG at the URL below or click the 'Register API' button shown when you log into the BC Data Catalogue and see your dashboard page.
https://argg.apps.gov.bc.ca/int/
Figure 1: Register API button in BCDC
The first section of the submission form requires a URL to the OpenAPI specification for the API you wish to register. Providing this URL will auto-populate part of the form. Examples can be found in the bcgov/api-specs repository.
Please provide the public URL directly to the JSON file as shown below (raw in GitHub). https://raw.githubusercontent.com/bcgov/api-specs/master/bcgnws/bcgnws.json
Although you may begin the registration process without an OpenAPI specification, it is good practice to provide a specification file for all RESTful APIs in the OpenAPI (3.x) format. Specification files can be hosted in the GitHub bcgov/api-specs repository.
If IDIR authentication is required for your specification file, it can also be hosted in the B.C. Data Catalogue.
The General API information section can be auto-populated using your OpenAPI spec from the previous section along with the ability to manually change any text. Required fields are marked with a red asterisk.
The API owner section is used to record the contact person to be listed in the API metadata record. If you are completing the ARGG submission form on behalf of the API owner, click no to provide your additional contact information to DataBC Gateway administrators. This will allow DataBC to contact you if follow-up questions arise.
ARGG will create a draft metadata record on your behalf once the submission form is complete. If you already have a published metadata record for the API, providing it here will ensure that another record is not created.
The access section is used in the creation of a draft metadata record and includes the exact values found in the BC Data Catalogue.
Registration with the API Gateway is optional. If you wish to make use of the API Gateway click 'Yes' and fill out the new fields which appear on your screen.
Throttling Access: This feature allows you to limit the maximum number of requests that can be submitted to your API per timeframe. If you select 'yes', a DataBC administrator will get in touch with you to define the exact values.
Restricting access with API keys: If enabled, this feature will require users to provide an API key to send requests to your API. As with rate limiting, a DataBC administrator will get in touch with you to confirm the details.