IP Address Enrichment API
This topic provides an introduction to the API, how to configure the API, types of methods and calls, and cURL examples.
Introduction to the API
NetObserv Flow provides an API for managing user-defined metadata (UDM) entries. The API allows for creating, reading, updating, and deleting UDM entries.
Configuring the API
To enable the API, set the following configuration values:
-
EF_PROCESSOR_ENRICH_IPADDR_METADATA_ENABLE: true -
EF_PROCESSOR_ENRICH_IPADDR_METADATA_API_ENABLE: true -
EF_PROCESSOR_ENRICH_IPADDR_METADATA_USERDEF_PATH: /etc/juniper/metadata/ipaddrs.yml*You can configure this setting to any location. However, it must be set to a specific value.
API Context
API Replaces YAML File Usage
Using this API replaces manual updates to the UDM YAML file. The API updates the file to reflect the latest state but prevents the product from noticing or re-reading YAML file changes. Make sure the comments do not contain critical information before using the API.
Create or update calls, such as CreateUdm, removes all comments and
might reorder stanzas in the file. The resulting file contains only data, excluding
comments and formatting.
Warning About Caching
NetObserv caches UDM entries in memory. Modifications made through this API won't take immediate effect due to caching. The cache lasts for two hours by default.
API Methods
This section lists available API methods and provides examples for each.
- CountUdms:
POST /api/v1/enrich/ipaddr/udm.v1.UdmService/CountUdms - ListUdms:
POST /api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdms - ListUDMKeys:
POST /api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdmKeys - CreateUdm:
POST /api/v1/enrich/ipaddr/udm.v1.UdmService/CreateUdm - BatchCreateUdms:
POST /api/v1/enrich/ipaddr/udm.v1.UdmService/BatchCreateUdm - DeleteUdm :
POST /api/v1/enrich/ipaddr/udm.v1.UdmService/DeleteUdm - UpdateUdm:
POST /api/v1/enrich/ipaddr/udm.v1.UdmService/UpdateUdm - BatchUpdateUdms:
POST /api/v1/enrich/ipaddr/udm.v1.UdmService/BatchUpdateUdms
CountUdms: POST
/api/v1/enrich/ipaddr/udm.v1.UdmService/CountUdms
Returns the number of items in the DB.
This example assumes you begin with the following set of UDM entries.
Example
# using curl
curl --json "{}" http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/CountUdms
Output
{
"count": 4
}ListUdms: POST
/api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdms
Returns a record that match the given key. Converts non-string metadata values, such as numbers, into strings.
Detailed Logic
The DB returns results based on the following conditions:
-
Without a key, the entire DB is returned.
-
With the
exactoption set totrue, the key is matched exactly. -
With the
exactoption set tofalse, all DB entries matching the key are returned. -
If no key is specified, the
exactoption is ignored, and all UDMs are returned.
If the key is:
-
An IP address:
The IP address is returned if it exists. Any CIDR or Range within the given CIDR is also returned if applicable.
-
A CIDR:
Any IP, CIDR, or Range within the given CIDR is returned. For a Range, the first and last IPs must be within the CIDR. For example, in
192.168.1.0/24, the first IP is192.168.1.0and the last IP is192.168.1.255. -
A Range:
Any IP, CIDR, or Range within the given Range is returned. For a CIDR, ensure the first and last IPs fall within the Range. The first and last IPs must be within the Range. For a given range R1, the database returns range R2 if R1.From <= R2.From and R2.To <= R1.To.
ListUdms is safe for concurrent calls. You can
safely call ListUdms concurrently for each key when querying multiple
keys.This example assumes you begin with the following set of UDM entries.
# Example ipaddrs.yml file
192.0.2.0/24:
internal: true
192.0.2.192/26:
name: atlanta_guest_wifi
vlan: 1001
tags:
- wifi
- dhcp
metadata:
dhcp.pool.name: atlanta_guest_wifi
.site.id: atlanta
192.0.2.194-192.0.2.198:
metadata:
.site.bldg.id: hq
.site.floor.id: 2
.site.rack.id: 1
192.0.2.194:
metadata:
device.type.name: wifi_apExample: List all UDM entries
# using curl
curl --json "{}" http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdmsOutput
{
"udms": [
{
"key": "192.0.2.194-192.0.2.198",
"metadata": {
".site.bldg.id": "hq",
".site.floor.id": "2",
".site.rack.id": "1"
}
},
{
"key": "192.0.2.194",
"metadata": {
"device.type.name": "wifi_ap"
}
},
{
"key": "192.0.2.0/24",
"internal": true
},
{
"key": "192.0.2.192/26",
"name": "atlanta_guest_wifi",
"tags": [
"wifi",
"dhcp"
],
"vlan": "1001",
"metadata": {
".site.id": "atlanta",
"dhcp.pool.name": "atlanta_guest_wifi"
}
}
]
}
Example: Search UDM Entries
# using curl
curl --json '{"key":"192.0.2.200", "exact":false}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdms
Output
{
"udms": [
{
"key": "192.0.2.192/26",
"name": "atlanta_guest_wifi",
"tags": [
"wifi",
"dhcp"
],
"vlan": "1001",
"metadata": {
".site.id": "atlanta",
"dhcp.pool.name": "atlanta_guest_wifi"
}
},
{
"key": "192.0.2.0/24",
"internal": true
}
]
}ListUDMKeys: POST
/api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdmKeys
Return keys matching the given key. This API is equivalent to calling
ListUdms on the key and returns only UDMs keys. If no key is provided,
it returns all keys. The rules are the same as specified in the ListUDMs Method.
The following examples assume you begin with this set of UDM entries.
List All Keys
# using curl
curl --json '{}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdmKeys
Output
{
"keys": [
"192.0.2.0/24",
"192.0.2.192/26",
"192.0.2.194-192.0.2.198",
"192.0.2.194"
]
}List a specific key
# using curl
curl --json '{"key":"192.0.2.194", "exact":true}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdmKeys
Output
{
"keys": [
"192.0.2.194"
]
}List all keys matching a given key
# using curl
curl --json '{"key":"192.0.2.200", "exact":false}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdmKeys
Output
{
"keys": [
# Both of these CIDRs contain the given IP.
"192.0.2.0/24",
"192.0.2.192/26"
]
}CreateUdm: POST
/api/v1/enrich/ipaddr/udm.v1.UdmService/CreateUdm
Creates a UDM entry. Returns an error if the given key already exists.
# using curl
curl --json '{"udm": { "key": "192.0.3.0/24", "name": "my_udm", "vlan": 2, "tags":["tag1", "tag2"]}}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/CreateUdm
Output
{
"key": "192.0.3.0/24",
"name": "my_udm",
"tags": [
"tag1",
"tag2"
],
"vlan": "2"
}BatchCreateUdms: POST
/api/v1/enrich/ipaddr/udm.v1.UdmService/BatchCreateUdm
Creates the given UDMs and returns them. Returns an error if any UDMs exist. Save updates to the .yml file atomically.
# using curl
curl --json '{"requests":[
{"udm": { "key": "192.0.4.0/24", "name": "my_udm2", "vlan": 4, "tags":["tag3", "tag4"]}},
{"udm": { "key": "192.0.5.0/24", "name": "my_udm3", "vlan": 5, "tags":["tag5", "tag6"]}}
]}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/BatchCreateUdms
Output
{
"udms": [
{
"key": "192.0.4.0/24",
"name": "my_udm2",
"tags": [
"tag3",
"tag4"
],
"vlan": "4"
},
{
"key": "192.0.5.0/24",
"name": "my_udm3",
"tags": [
"tag5",
"tag6"
],
"vlan": "5"
}
]
}This output shows the status of the DB after running the above example commands:
curl --json '{}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdmKeys
{
"keys": [
"192.0.2.0/24",
"192.0.2.192/26",
"192.0.3.0/24",
"192.0.4.0/24",
"192.0.5.0/24",
"192.0.2.194-192.0.2.198",
"192.0.2.194"
]
}DeleteUdm : POST
/api/v1/enrich/ipaddr/udm.v1.UdmService/DeleteUdm
Deletes the specified UDM. The key must match exactly. Deletes are atomic and updates the .yml file.
Example
# using curl
curl --json '{"key": "192.0.3.0/24"}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/DeleteUdm
Output
{}Result
curl --json '{}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/ListUdmKeys
{
"keys": [
"192.0.2.0/24",
"192.0.2.192/26",
# note 192.0.3.0/24 is gone
"192.0.4.0/24",
"192.0.5.0/24",
"192.0.2.194-192.0.2.198",
"192.0.2.194"
]
}UpdateUdm: POST
/api/v1/enrich/ipaddr/udm.v1.UdmService/UpdateUdm
-
Updates the given UDM with the provided data. The
update_maskfield specifies the fields to update. If empty, all fields are updated to their "zero value," including unspecified ones. -
Returns the updated UDM or an error if the key is missing.
Example: Without an update_mask
{
"udms": [
{
"key": "192.0.4.0/24",
"name": "my_udm2",
"tags": [
"tag3",
"tag4"
],
"vlan": "4"
}
]
}# using curl
curl --json '{"udm":{"key": "192.0.4.0/24", "vlan": 5}}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/UpdateUdm
Output
{
"key": "192.0.4.0/24",
"vlan": "5"
}This command lacks an update_mask, so all unspecified fields in the UDM
object were cleared.
Example: With an update_mask
{
"udms": [
{
"key": "192.0.5.0/24",
"name": "my_udm3",
"tags": [
"tag5",
"tag6"
],
"vlan": "5"
}
]
}# Only update vlan and tags fields
# using curl
curl --json '{"udm":{"key": "192.0.5.0/24", "vlan": 6, "tags":["tag7"]}, "update_mask": "vlan,tags"}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/UpdateUdm
Output
{
"key": "192.0.5.0/24",
"name": "my_udm3", // name not changed
"tags": [ // all tags replaced
"tag7"
],
"vlan": "6" // vlan updated
}The command included an update_mask. As a result, only the
vlan and tags fields were updated.
BatchUpdateUdms: POST
/api/v1/enrich/ipaddr/udm.v1.UdmService/BatchUpdateUdms
Updates the UDMs with the provided data. Use the UpdateMask field to
specify fields for updating. If the UpdateMask is empty, all fields,
including unspecified ones, are updated to their "zero value." See the example below for
details.
Returns updated UDMs or an error if any keys are missing. Updates are atomic and saved to the .yml file.
BatchUpdateUdmsuses aBatchUpdateUdmsRequest struct
containing:
-
A slice of
UpdateUdmRequeststructs . -
A single
UpdateMaskfield for the batch.
Each UpdateUdmRequest struct has its own UpdateMask,
which is ignored.
Without an update_mask
# using curl
curl --json '{"requests":[ {"udm": { "key": "192.0.2.0/24", "name": "new_name"}},
{"udm": { "key": "192.0.2.194", "name": "new_name2"}} ]}' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/BatchUpdateUdms
Output
{
"udms": [
{
"key": "192.0.2.0/24",
"name": "new_name"
},
{
"key": "192.0.2.194",
"name": "new_name2"
}
]
}No update_mask was specified, so all fields not mentioned were
cleared.
With an
update_mask
-
Update only the tags and metadata fields.
-
The
vlanin the first UDM entry and the name in both UDMs are not updated. -
Only the top-level
update_maskfield is valid. -
The first request's
"update_mask":"name"is ignored.
### Update only the tags and metadata fields; inner "update_mask":"name" is ignored
# using curl
curl --json '{"requests":[
{"udm": { "key": "192.0.2.0/24", "name": "not_changed", "vlan":2, "tags":["tag8"]}, "update_mask": "name"},
{"udm": { "key": "192.0.2.194", "name": "also_not_changed", "metadata":{"key":"value"}}}
],
"update_mask": "tags,metadata" }' http://localhost:8080/api/v1/enrich/ipaddr/udm.v1.UdmService/BatchUpdateUdms
Output
{
"udms": [
{
"key": "192.0.2.0/24",
"name": "new_name",
"tags": [
"tag8"
]
},
{
"key": "192.0.2.194",
"name": "new_name2",
"metadata": {
"key": "value"
}
}
]
}BatchUpdateUdms request, only the
top-level update_mask field is used. The update_mask
field in each request object is ignored.