mirror of
https://github.com/peeringdb/peeringdb.git
synced 2024-05-11 05:55:09 +00:00
Support 202102 (#950)
* install django-grainy * nsp to grainy first iteration * nsp to grainy second iteration * grainy and django-grainy pinned to latest releases * Fix typo * Update djangorestframework, peeringdb, django-ratelimit * Rewrite login view ratelimit decorator * Relock pipfile * add list() to make copy of dictionaries before iterating * relock pipfile with python3.9 change docker to use python3.9 * add ordering to admin search queryset for deskproticket and email * add org api key and begin to write tests * additional key tests * add drf-api-keys to pipfile * Wire orgapikey to modelviewsetpermissions * Update api key helper functions * add put test * Add Org API key tab to frontend * Add user api key model * Update user key handling and tests * Update APIPermissionsApplicator to make it work w requests * Add org api key perm panel * add org key permissions * Add user api key views * Add templates for handling user api key (adding, not revoking) * relock pipfile * assorted fixes and tweaks * Add general user group permissions and org user group perms * refactor org api key perms * Add tests for api keys * Add docstrings to permissions helpers * Add api key examples * squash migrations * remove custom api key header config * Change api key test setup * Update permissions for grainy change * Bump up pipfile and pipfile.lock * Add API Key to Verification Queue Item * Delete travis * Add workaround to Dockerfile * update pipfile and sort out migrations * Add comment to Dockerfile * Re-add API Key migrations * Add locale to .gitignore * remove suggest functionality from ix * Update test to recognize that IX api no longer has suggest function * Add test to outlaw POSTing an IX w its org equal to the suggest entity org * Add meta information geowarning * Add alert to demonstrate UI * Add error to fac update * Add template warning for geovalidation * Add geowarning meta js * cover absent meta_response test case * Update styles for geowarning * refactor geotag warning implementation * null lat and long on unsuccessful geo locate * modify geovalidation frontend update * Add deskproticket model email field * Add missing span * add email to org keys * Add email to org key tests * update serializer with rdap validation wrapper * update admin for api keys * Enable writing an email as part of org key creation * Add email validation to org api key form * fix css style on perm row * Add suggested info to api response * display suggested address on frontend * add needs geocode to serializer * save lat long on forward geonormalization * add address suggestion submit button * Add suggested address popin to ADD facility form * Fix css * add lat and long rounding to geocodenabled model clean method * add migration and regression test for lat long decimal db constraint * Add another regression test for model decimal places * Get deskpro functions passing isort and flake * Update ticket_queue_deletion_prevented * update ticket_queue_deletion_prevented for use with org api key * add template for org key dpt from asnauto skipvq * Update deskproticket for rdap error * add facility aka * add aka to serializer and views * black and isort test api keys * fix typo in org key deskpro template * skip or rewrite unapplicable org key tests, and add as_set tests * adjust api key test comments * Add vqi_notify to signals * Add reversion comments for api keys and helper function * update how org keys are added to verification queue items * rename verification queue item fk from api_key to org_key * fix group id error * update key tests with correct http header info * check both user and key, not just user * templates fiex * adapt deskpro integration to work with email only * make org api keys editable for desc and email * pipfile relock * edit test setupdata settings for groups * Change comment to signify we don't need to remove code * address untranslated accept button * Add docstrings to the serializer functions * Add loading shim * Add migration for all longname and aka * Add aka and long name to views and serializers * delete migration w decimals * standardize serializer lat and long fields * Add clean rounding for lat and long * fix serializer error * api key admin improvements * fix linebreak in user api key form * remove debug prints * Add rounding util * Add rounding to lat and long fields * remove 'clean' from geocode method (logic now in admin form) * remove erroneous tests * revert serializer changes * Fix migrations * Add long name and aka to admin models * Update API key docs * Add documentation for api keys * fix typo * fix org api key revoke broken by editable api keys * doc tweaks * doc tweaks * doc tweaks * black format * fix migration hierarchy * docs * docs * api key permissions screenshot * formatting * formatting * padding fixed * remove one image * fix get_user_from_request type checking take out POST only valdiator for entity suggest * didnt mean to commit the django-peeringdb mount * fix suggest on PUT net fix tests * black formatting * update org key permission template * install rust for cryptography * pipfile relock (django-peeringdb to 2.6) Co-authored-by: Stefan Pratter <stefan@20c.com> Co-authored-by: Elliot Frank <elliot@20c.com>
This commit is contained in:
Matt Griswold
GitHub
131
docs/api_keys.md
Normal file
131
docs/api_keys.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# API Keys
|
||||
|
||||
PeeringDB offers API keys for authenticating API requests. There are two main forms of API keys:
|
||||
|
||||
## Organization-level API Keys
|
||||
|
||||
These API keys are created and revoked from the organization admin panel. Each key gets its own custom permissions, which can be modified from the "org api key permissions" panel.
|
||||
|
||||
Each key must have an email attached to it; this is because keys may be allowed to create and modify data in PeeringDB, and we need a contact to reach out to in case of questions.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## User-level API Keys
|
||||
|
||||
These API key are tied to a individual user account and can be created from the user profile page. There are only two permission levels: a normal key will mirror the same permissions of the user, while a readonly key will have readonly permissions to all the same namespaces as the user.
|
||||
|
||||
|
||||
|
||||
## Copy/Write down keys immediately
|
||||
|
||||
**One thing to note** is that the full api key string is only ever exposed to the user or organization at its moment of creation. If this string is lost, then the user or organization should revoke that key and create and permission a new one.
|
||||
|
||||
|
||||
## Commandline example using Python and Requests
|
||||
API keys allow developers to interact with their PeeringDB account programmatically, rather than through the website. Here is an example script in Python. It uses the module Requests to GET data about a particular Facility, and then sends a PUT request to modify that data.
|
||||
|
||||
This example assumes we have an environment variable set with our API Key. To do that from the commandline, we can run:
|
||||
|
||||
```sh
|
||||
export API_KEY="[created api key string]"
|
||||
```
|
||||
|
||||
Then the Python script would look like the following. First we get the API key from the environment:
|
||||
|
||||
```py
|
||||
import os
|
||||
|
||||
import requests
|
||||
|
||||
API_KEY = os.environ.get("API_KEY")
|
||||
```
|
||||
|
||||
We set the url for the Facility we want to interact with. Note the `/api` in the URL, which signals we are making calls to the REST API.
|
||||
|
||||
```py
|
||||
URL = "https://www.peeringdb.com/api/fac/10003"
|
||||
```
|
||||
|
||||
We set the headers to include our API key as authorization. Printing the `headers` variable should allow us to see the API key.
|
||||
|
||||
```py
|
||||
headers = {"AUTHORIZATION": "Api-Key " + API_KEY}
|
||||
print(headers)
|
||||
```
|
||||
|
||||
First we make a GET request, to simply get data about example Facility number 10003
|
||||
|
||||
```py
|
||||
response = requests.get(URL, headers=headers)
|
||||
data = response.json()["data"][0]
|
||||
print(data)
|
||||
```
|
||||
|
||||
Printing this data allows us to see what fields we would like to change. Let's say we decide to change the name of this facility. We overwrite the value for key "name"
|
||||
|
||||
```py
|
||||
data["name"] = "Newly decided name"
|
||||
```
|
||||
|
||||
Then we use a PUT request to send that modified data back to PeeringDB.
|
||||
Note that this time, we must provide data to the API, using the keyword argument "data"
|
||||
|
||||
```py
|
||||
put_response = requests.put(URL, headers=headers, data=data)
|
||||
```
|
||||
|
||||
We can print the status code to see if our request was successful.
|
||||
|
||||
```py
|
||||
print(put_response.status_code)
|
||||
```
|
||||
This will return a code 200 to signal success.
|
||||
|
||||
Additionally the content of the request should include data for the now modified Facility
|
||||
|
||||
```py
|
||||
print(put_response.json())
|
||||
```
|
||||
|
||||
Would return a dictionary of the values of the now modified Facility.
|
||||
|
||||
## Commandline example using Curl
|
||||
|
||||
API keys provide a cleaner way to authenticate api requests. PeeringDB recommends the commandline user creates a API_KEY variable like so
|
||||
|
||||
```sh
|
||||
export API_KEY="[created api key string]"
|
||||
```
|
||||
then requests can be made with Curl like in the following examples:
|
||||
|
||||
### GET
|
||||
The following request would return JSON data coresponding to the [ChiX](https://www.peeringdb.com/ix/239) Internet Exchange.
|
||||
|
||||
```sh
|
||||
curl -H "Authorization: Api-Key $API_KEY" -H "Content-Type: application/json" -X GET https://peeringdb.com/api/ix/239
|
||||
```
|
||||
|
||||
### POST
|
||||
|
||||
The following request would create a new Network under the organization [United IX](https://www.peeringdb.com/org/10843).
|
||||
|
||||
```sh
|
||||
curl -H "Authorization: Api-Key $API_KEY" -H "Content-Type: application/json" -X POST --data "{\""org_id"\":\"10843\", \""name"\":\"Brand New Network\", \""asn"\":\"63311\"}" https://peeringdb.com/api/net
|
||||
```
|
||||
|
||||
### PUT
|
||||
|
||||
The following request would update the data about a particular Network, [ChIX Route Servers](https://www.peeringdb.com/net/7889), in particular changing the name to "Edited Name".
|
||||
|
||||
```sh
|
||||
curl -H "Authorization: Api-Key $API_KEY" -H "Content-Type: application/json" -X PUT --data "{\""org_id"\":\"10843\", \""name"\":\"Edited Name\", \""asn"\":\"33713\"}" https://peeringdb.com/api/net/7889
|
||||
```
|
||||
|
||||
### DELETE
|
||||
The following request would delete the [ChiX](https://www.peeringdb.com/ix/239) Internet Exchange. The API key holder would need delete privileges to that particular Exchange.
|
||||
|
||||
```sh
|
||||
curl -H "Authorization: Api-Key $API_KEY" -H "Content-Type: application/json" -X DELETE https://peeringdb.com/api/ix/239
|
||||
```
|
||||
BIN
docs/img/org-key-add.png
Executable file
BIN
docs/img/org-key-add.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
BIN
docs/img/org-key-added.png
Executable file
BIN
docs/img/org-key-added.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
BIN
docs/img/org-key-permissions.png
Executable file
BIN
docs/img/org-key-permissions.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
BIN
docs/img/user-key-add.png
Executable file
BIN
docs/img/user-key-add.png
Executable file
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Reference in New Issue
Block a user