## Overview

> [!WARNING]
>
> **Preview
> --- Shadow API Discovery**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

This page provides reference syntax for managing Apigee Shadow API Discovery from the Apigee
Management (APIM) APIs. Documentation for the Management APIs related to Shadow API Discovery,
including information on each field in a request, can be found at
<https://cloud.google.com/apigee/docs/reference/apis/apim/rest>
and
<https://cloud.google.com/apigee/docs/reference/apis/apim/rpc>

For an overview of Shadow API Discovery and instructions for managing it using the Apigee UI in Cloud
console, see
[Shadow API discovery](https://docs.cloud.google.com/apigee/docs/api-observation/shadow-api-discovery.md.txt).
Information on the general behaviors and limitations of Shadow API Discovery is in
[Behaviors and limitations](https://docs.cloud.google.com/apigee/docs/api-observation/shadow-api-discovery.md.txt#behaviors-and-limitations).

## Parameters in reference API calls

The API calls on this page can use the following parameters, which refer to either your
Apigee account information (such as your project) or information used when creating observation
jobs. See
[Create observation jobs](https://docs.cloud.google.com/apigee/docs/api-observation/shadow-api-discovery.md.txt#create-observation-jobs)
for more information on each of these fields.

- <var translate="no">OBSERVATION_JOB_LOCATION</var> is a location for an observation job.
- <var translate="no">OBSERVATION_JOB_NAME</var> is an observation job name.
- <var translate="no">OBSERVATION_SOURCE_LOCATION</var> is a source location for the observation job.
- <var translate="no">OBSERVATION_SOURCE_NAME</var> is an observation source name.
- <var translate="no">PROJECT</var> is your Apigee project.

## Create an observation job

Creating an observation job requires multiple steps/API requests.

1. **Create an observation source:** To create a new observation source rather than using an existing one, make a POST request to the observationSources endpoint with the observation source details.  

   ```
   curl \ https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_SOURCE_LOCATION/observationSources?observation_source_id=OBSERVATION_SOURCE_NAME \
   -X POST \
   -H 'Content-type: application/json' \
   -d @- <<'EOF'
   {
     "gclbObservationSource": {
       "pscNetworkConfigs": [
         {
           "network": "projects/PROJECT/global/networks/{network_name}",
           "subnetwork":"projects/PROJECT/regions/OBSERVATION_SOURCE_LOCATION/subnetworks/{subnet_name}"
         }
       ]
     }
   }
   EOF
   ```
   Creation of an observation source requires several minutes and starts an [LRO](https://google.aip.dev/151), with a response like this:

   ```
   {
   "name": "projects/{project/locations/OBSERVATION_SOURCE_LOCATION/operations/operation-",
   "metadata": {
     "@type": "type.googleapis.com/google.cloud.apim.vl.ApiDiscoveryOperationMetadata",
     "createTime": "",
     "target": "projects/PROJECT/locations/OBSERVATION_SOURCE_LOCATION/observationSources/OBSERVATION_SOURCE_NAME",
     "verb": "create",
     "requestedCancellation": false,
     "apiVersion": "vl"
   },
   "done": false
   }
   ```
2. To view the newly created observation source:

   ```
   curl \
   https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_SOURCE_LOCATION/observationSources/OBSERVATION_SOURCE_NAME
   ```
3. **Create an observation job:** Create a job that looks for shadow APIs using the source you just created:

   ```
   curl \
   https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_JOB_LOCATION/observationJobs?observation_job_id=OBSERVATION_JOB_NAME \
   -X POST \
   -H 'Content-type: application/json' \
   -d @- <<'EOF'
   {
     "sources": [
       "projects/PROJECT/locations/OBSERVATION_SOURCE_LOCATION/observationSources/OBSERVATION_SOURCE_NAME"
     ]
   }
   EOF
   ```

## Enable an observation job

Use the following command to enable a new observation job or a disabled existing job.

```
curl https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_JOB_LOCATION/observationJobs/OBSERVATION_JOB_NAME:enable \
-X POST \
-H 'Content-type: application/json' \
-d @- <<'EOF'
{}
EOF
```

## View discovered APIs

To view APIs discovered by enabled observation jobs, submit this command:

```
curl https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_JOB_LOCATION/observationJobs/OBSERVATION_JOB_NAME/apiObservations \
-X GET
```

## Manage tags on observation results

To list the tags already added to results:

```
curl -H "https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_JOB_LOCATION:listApiObservationTags"
  
```

To manage tags:

```
curl -H "Content-Type: appication/json" \
"https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_JOB_LOCATION/observationJobs/OBSERVATION_JOB_NAME/apiObservations:batchEditTags" \
-X POST -d @- <<'EOF'
{
  "requests": [
    {
      "apiObservationId": "API_OBSERVATION_ID",
      "tagActions": [
      {
        "tag": "demo",
        "action": "REMOVE"
      },
      {
        "tag": "Needs Attentions",
        "action": "ADD"
      }]
    }
  ]
}
EOF
```

## Disable an observation job

This request disables an observation job without deleting it.

```
curl https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_JOB_LOCATION/observationsJobs/OBSERVATION_JOB_NAME:disable \
-X POST \
-H 'Content-type: application/json' \
-d @- <<'EOF'
{
}
```

## Delete an observation job

This request deletes an observation job.

```
curl -X DELETE https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_JOB_LOCATION/observationJobs/OBSERVATION_JOB_NAME
```

## Delete an observation source

This request deletes an observation source.

```
curl -X DELETE https://apim.googleapis.com/v1alpha/projects/PROJECT/locations/OBSERVATION_SOURCE_LOCATION/observationSources/OBSERVATION_SOURCE_NAME
```