gravitl/netmaker
1
1
Fork 0
mirror of https://github.com/gravitl/netmaker.git synced 2025-09-13 16:44:52 +08:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #88 from gravitl/feature_v0.2_apidocs

Browse source 
Feature v0.2 apidocs
This commit is contained in:
Alex 2021-04-13 16:29:24 -04:00 • committed by GitHub
commit a05a0f307d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 102 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

166
docs/API.md
View file

@ -1,10 +1,12 @@
# API Reference Doc
## GENERAL
Most actions that can be performed via API can be performed via UI. We recommend managing your networks using our official netmaker-ui project. That said, Netmaker is API based, and all functions can also be achieved via API calls. If you feel the need to work with Netmaker via API, we've provided some documentation below to help guide you.
#### Authentication
In general, API calls must be authenticated via a header of the format `-H "Authorization: Bearer <YOUR_SECRET_KEY>"` There are two methods of obtaining YOUR_SECRET_KEY:
1. Using the masterkey. By default, this value is "secret key," but you should change this on your instance and keep it secure. This value can be set via env var at startup or in a config file. See the [getting started](./GETTING_STARTED.md) documentation for more details.
1. Using the masterkey. By default, this value is "secret key," but you should change this on your instance and keep it secure. This value can be set via env var at startup or in a config file (config/environments/< env >.yaml). See the [getting started](./GETTING_STARTED.md) documentation for more details.
2. Using a JWT recieved for a node. This can be retrieved by calling the `/api/nodes/<network>/authenticate` endpoint, as documented below.
#### Format
@ -13,14 +15,21 @@ In general, requests will take the format of `curl -H "Authorization: Bearer <YO
## NETWORKS
**Get All Networks:** `/api/networks`, `GET`
**Create Network:** `/api/network`, `POST`
**Get Network:** `/api/networks/{network id}`, `GET`
**Update Network:** `/api/networks/{network id}`, `PUT`
**Delete Network:** `/api/networks/{network id}`, `DELETE`
**Cycle PublicKeys on all Nodes:** `/api/networks/{network id}/keyupdate`, `POST`
### Network API Call Examples
**Get All Networks:** `curl -H "Authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/networks | jq`
**Create Network:** `curl -d '{"addressrange":"10.70.0.0/16","netid":"skynet"}' -H "Authorization: Bearer YOUR_SECRET_KEY" -H 'Content-Type: application/json' localhost:8081/api/networks`
@ -36,40 +45,59 @@ In general, requests will take the format of `curl -H "Authorization: Bearer <YO
## ACCESS KEYS
**Get All Keys:** `/api/networks/{network id}/keys`, `GET`
**Create Key:** `/api/networks/{network id}/keys`, `GET`
**Delete Key:** `/api/networks/{network id}/keys/{keyname}`, `DELETE`
### Access Key API Call Examples
**Get All Keys:** `curl -H "Authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/networks/skynet/keys | jq`
**Create Key:** `curl -d '{"uses":10,"name":"mykey"}' -H "Authorization: Bearer YOUR_SECRET_KEY" -H 'Content-Type: application/json' localhost:8081/api/networks/skynet/keys`
**Delete Key:** `curl -X DELETE -H "Authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/networks/skynet/keys/mykey`
## NODES (COMPUTERS)
**Get All Nodes:** `/api/nodes`, `GET`
**Get Network Nodes:** `/api/nodes/{network id}`, `GET`
**Create Node:** `/api/nodes/{network id}`, `POST`
**Get Node:** `/api/nodes/{network id}/{macaddress}`, `GET`
**Update Node:** `/api/nodes/{network id}/{macaddress}`, `PUT`
**Delete Node:** `/api/nodes/{network id}/{macaddress}`, `DELETE`
**Check In Node:** `/api/nodes/{network id}/{macaddress}/checkin`, `POST`
**Create a Gateway:** `/api/nodes/{network id}/{macaddress}/creategateway`, `POST`
**Delete a Gateway:** `/api/nodes/{network id}/{macaddress}/deletegateway`, `DELETE`
**Uncordon (Approve) a Pending Node:** `/api/nodes/{network id}/{macaddress}/uncordon`, `POST`
**Get Last Modified Date (Last Modified Node in Network):** `/api/nodes/adm/{network id}/lastmodified`, `GET`
**Authenticate:** `/api/nodes/adm/{network id}/authenticate`, `POST`
### Example Node API Calls
**Get All Nodes:**`curl -H "Authorization: Bearer YOUR_SECRET_KEY" http://localhost:8081/api/nodes | jq`
**Get All Keys:** `curl -H "Authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/networks/skynet/keys | jq`
**Create Key:** `curl -d '{"uses":10,"name":"mykey"}' -H "Authorization: Bearer YOUR_SECRET_KEY" -H 'Content-Type: application/json' localhost:8081/api/networks/skynet/keys`
**Delete Key:** `curl -X DELETE -H "Authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/networks/skynet/keys/mykey`
## NODES (COMPUTERS)
**Get All Nodes:** `/api/nodes`, `GET`
**Get Network Nodes:** `/api/nodes/{network id}`, `GET`
**Create Node:** `/api/nodes/{network id}`, `POST`
**Get Node:** `/api/nodes/{network id}/{macaddress}`, `GET`
**Update Node:** `/api/nodes/{network id}/{macaddress}`, `PUT`
**Delete Node:** `/api/nodes/{network id}/{macaddress}`, `DELETE`
**Check In Node:** `/api/nodes/{network id}/{macaddress}/checkin`, `POST`
**Create a Gateway:** `/api/nodes/{network id}/{macaddress}/creategateway`, `POST`
**Delete a Gateway:** `/api/nodes/{network id}/{macaddress}/deletegateway`, `DELETE`
**Uncordon (Approve) a Pending Node:** `/api/nodes/{network id}/{macaddress}/uncordon`, `POST`
**Get Last Modified Date (Last Modified Node in Network):** `/api/nodes/adm/{network id}/lastmodified`, `GET`
**Authenticate:** `/api/nodes/adm/{network id}/authenticate`, `POST`
### Example Node API Calls
**Get All Nodes:**`curl -H "Authorization: Bearer YOUR_SECRET_KEY" http://localhost:8081/api/nodes | jq`
**Get Network Nodes:** `curl -H "Authorization: Bearer YOUR_SECRET_KEY" http://localhost:8081/api/nodes/skynet | jq`
**Create Node:** `curl -d '{ "endpoint": 100.200.100.200, "publickey": aorijqalrik3ajflaqrdajhkr,"macaddress": "8c:90:b5:06:f1:d9","password": "reallysecret","localaddress": "172.16.16.1","accesskey": "aA3bVG0rnItIRXDx","listenport": 6400}' -H 'Content-Type: application/json' -H "authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/nodes/skynet`
**Get Node:** `curl -H "Authorization: Bearer YOUR_SECRET_KEY" http://localhost:8081/api/nodes/skynet/{macaddress} | jq`
**Update Node:** `curl -X PUT -d '{"name":"laptop1"}' -H 'Content-Type: application/json' -H "authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/nodes/skynet/8c:90:b5:06:f1:d9`
@ -85,45 +113,55 @@ In general, requests will take the format of `curl -H "Authorization: Bearer <YO
**Get Last Modified Date (Last Modified Node in Network):** `curl -H "authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/nodes/adm/skynet/lastmodified`
**Authenticate:** `curl -d '{"macaddress": "8c:90:b5:06:f1:d9", "password": "YOUR_PASSWORD"}' -H 'Content-Type: application/json' localhost:8081/api/nodes/adm/skynet/authenticate`
## USERS
**Note:** Only able to create Admin user at this time. The "user" is only used by the [user interface](https://github.com/gravitl/netmaker-ui) to authenticate the single admin user.
**Get User:** `/api/users/{username}`, `GET`
**Update User:** `/api/users/{username}`, `PUT`
**Delete User:** `/api/users/{username}`, `DELETE`
**Check for Admin User:** `/api/users/adm/hasadmin`, `GET`
**Create Admin User:** `/api/users/adm/createadmin`, `POST`
**Authenticate:** `/api/users/adm/authenticate`, `POST`
### Example User API Calls
### Users (only used for interface admin user at this time)
**Create Admin User:** "/users/createadmin", "POST"
**Check for Admin User:** "/users/hasadmin", "GET"
**Update User:** "/users/{username}", "PUT"
**Delete User:** "/users/{username}", "DELETE"
**Get User:** "/users/{username}", "GET"
**Authenticate User:** "/users/authenticate", "POST"
**Get User:**`curl -H "Authorization: Bearer YOUR_SECRET_KEY" http://localhost:8081/api/users/{username} | jq`
*note: users API does not use /api/ because of a weird bug. Will fix in future release.
**note: Only able to create Admin at this time. The "user" is only used by the [user interface](https://github.com/gravitl/netmaker-ui) to authenticate the single admin user.
**Update User:** `curl -X PUT -d '{"password":"noonewillguessthis"}' -H 'Content-Type: application/json' -H "authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/users/{username}`
**Delete User:** `curl -X DELETE -H "authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/users/{username}`
**Check for Admin User:**`curl -H "Authorization: Bearer YOUR_SECRET_KEY" http://localhost:8081/api/users/adm/hasadmin`
**Create Admin User:** `curl -d '{ "username": "smartguy", "password": "YOUR_PASS"}' -H 'Content-Type: application/json' -H "authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/users/adm/createadmin`
**Authenticate:** `curl -d '{"username": "smartguy", "password": "YOUR_PASS"}' -H 'Content-Type: application/json' localhost:8081/api/nodes/adm/skynet/authenticate`
## SERVER MGMT
### Files
**Get File:** "/meshclient/files/{filename}", "GET"
The Server Mgmt. API allows you to add and remove the server from networks.
## Example API CALLS
**Add to Network:** `/api/server/addnetwork/{network id}`, `POST`
**Remove from Network:** `/api/server/removenetwork/{network id}`, `DELETE`
**Note About Token:** This is a configurable value stored under config/environments/dev.yaml and can be changed before startup. It's a hack for testing, just provides an easy way to authorize, and should be removed and changed in the future.
#### Create a Network
curl -d '{"addressrange":"10.70.0.0/16","netid":"skynet"}' -H "Authorization: Bearer secretkey" -H 'Content-Type: application/json' localhost:8081/api/networks
#### Create a Key
curl -d '{"uses":10}' -H "Authorization: Bearer secretkey" -H 'Content-Type: application/json' localhost:8081/api/networks localhost:8081/api/networks/skynet/keys
#### Create a Node
curl -d '{ "endpoint": 100.200.100.200, "publickey": aorijqalrik3ajflaqrdajhkr,"macaddress": "8c:90:b5:06:f1:d9","password": "reallysecret","localaddress": "172.16.16.1","accesskey": "aA3bVG0rnItIRXDx","listenport": 6400}' -H 'Content-Type: application/json' -H "authorization: Bearer secretkey" localhost:8081/api/skynet/nodes
#### Get Networks
curl -H "Authorization: Bearer secretkey" -H 'Content-Type: application/json' localhost:8081/api/networks | jq
#### Get Network Nodes
curl -H "Authorization: Bearer secretkey" -H 'Content-Type: application/json' localhost:8081/api/skynet/nodes | jq
#### Update Node Settings
curl -X "PUT" -d '{"name":"my-laptop"}' -H 'Content-Type: application/json' -H "authorization: Bearer secretkey" localhost:8081/api/skynet/nodes/8c:90:b5:06:f1:d9
#### Delete a Node
curl -X "DELETE" -H "authorization: Bearer secretkey" localhost:8081/api/skynet/nodes/8c:90:b5:06:f1:d9
**Add to Network:** `curl -X POST -H "authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/server/addnetwork/{network id}`
**Remove from Network:** `curl -X DELETE -H "authorization: Bearer YOUR_SECRET_KEY" localhost:8081/api/server/removenetwork/{network id}`
## FILE SERVER
**Get File:** `/meshclient/files/{filename}`, `GET`
**Example:** `curl localhost:8081/meshclient/files/meshclient`