# Documentation for Test, Monitor, and Visualize Geospatial APIs 1.0.0

This documentation covers the powerful API testing features of Quetzly Validator to send requests to various geospatial services and APIs, ranging from basic requests to advanced testing scenarios.

## Getting to the API Section

1. **Launch** Quetzly Validator
2. **Click** the **API** icon in the left sidebar.
3. You'll see the main request interface with two panels:
   - **Left Panel**: Request configuration
   - **Right Panel**: Map viewer and responses

## Request Builder Interface

### Basic Request Setup

The top section contains the core request configuration:

#### 1. HTTP Method Selection
Choose from standard HTTP methods:
- **GET**: Retrieve data (most common for geospatial services)
- **POST**: Send data to create resources
- **PUT**: Update existing resources

#### 2. Service Type Selection
Select the type of service you're testing:
- **JSON**: Standard REST APIs - Geojson or Json
- **WMS**: Web Map Service
- **WFS**: Web Feature Service
- **Esri Map Service**: ArcGIS Map Services
- **Esri Feature Service**: ArcGIS Feature Services

#### 3. URL Input
Enter the endpoint URL you want to test. Examples:
```text
# ArcGIS Map Service
https://services.arcgis.com/example/arcgis/rest/services/layer/MapServer

# REST API
https://api.example.com/v1/data?f=json

# WMS GetCapabilities
https://example.com/geoserver/wms

# WFS GetFeature
https://example.com/geoserver/wfs
```

#### 4. Send Button
Click **Send** to execute the request and view the response.

## Advanced Request Configuration

### Query Parameters
Add custom query parameters to your requests:
1. **Click** the "Query Params" tab (active by default)
2. **Enter**parameter key-value pairs:
   - **Key**: Parameter name (e.g., `service`, `version`, `format`)
   - **Value**: Parameter value (e.g., `WMS`, `1.3.0`, `image/png`)
3. **Click** "Add" to create additional parameter pairs
4. **Click** "Remove" to delete unwanted parameters

**Note**: At the moment the query parameters can **only be used for a json type** request. Support for other types is still in developement. The other types use a simple GET request and can be visualized.

#### Example Parameters

**JSON Request with Parameters to ArcGIS Service:**
- `f`: Response format (json, pjson, etc.)
- `where`: SQL where clause
- `outFields`: Fields to return
- `geometry`: Spatial filter geometry
- `spatialRel`: Spatial relationship
- `returnGeometry`: Include geometry (true/false)

**GEOJSON Request with Parameters:**
```text
# Geojson Request
https://earthquake.usgs.gov/fdsnws/event/1/query
```
- `format`: geojson
- `starttime`: 2024-01-01
- `endtime`: 2024-01-02
- `minmagnitude`: 5

### Headers
Add custom HTTP headers for authentication or content type specification:
1. **Click** the "Headers" tab
2. **Add**header key-value pairs:
   - **Authorization**: `Bearer your-token-here`
   - **Content-Type**: `application/json`
   - **Accept**: `application/json`
   - **User-Agent**: `Quetzly/1.0`
3. **Click** "Add" for additional headers
4. **Click** "Remove" to delete headers

### Request Body
For POST, PUT, and PATCH requests, configure the request body:
1. **Click** the "Body" tab
2. **Edit** the JSON in the code editor
3. **Use** the built-in syntax highlighting and validation
4. **Format** your JSON properly for the target API

Example POST body for creating a feature:
```json
{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  },
  "properties": {},
  "id": 0
}
```

## Response Analysis

After sending a request, the response section becomes visible with detailed information:

### Response Status Bar
- **Status**: HTTP status code (200, 404, 500, etc.)
- **Time**: Request duration in milliseconds
- **Size**: Response size in bytes/KB/MB

### Response Tabs

#### Body Tab
View the raw response content:
- **JSON responses**: Formatted with syntax highlighting

#### Headers Tab
Inspect response headers:
- **Content-Type**: Response format
- **Content-Length**: Response size
- **Cache-Control**: Caching directives
- **Server**: Server information
- **Custom headers**: Service-specific headers

#### Layers Tab
For geospatial services, this tab shows:
- **Available layers**: Detected from service metadata
- **Layer properties**: Name, title, description
- **Add to map**: Checkboxes to add layers to the map viewer
- **Layer styling**: Basic styling

## Working with Geospatial Services

### ArcGIS Services

1. For Map services, add the ArcGIS service url all the way up to the /MapServer
   - `https://tigerweb.geo.census.gov/arcgis/rest/services/TIGERweb/State_County/MapServer`
2. For Feature services, add the ArcGIS service url all the way up to the /FeatureServer
   - `https://organization.example.com/<context>/rest/services/USA/FeatureServer`
3. The Map and/or layers will be added to the map and layer list

### JSON Requests

You can make custom Map and feature service queries by using the JSON request type.

**Map Service Query:**
1. Set service type to "JSON"
2. Add query endpoint: `/query`
3. Add parameters:
   - `f`: json
   - `where`: 1=1 (or specific filter)
   - `outFields`: \* (or specific fields)
   - `returnGeometry`: true

**Feature Service Operations:**
1. Set service type to "JSON"
2. Use endpoints like `/query`, `/addFeatures`, `/updateFeatures`
3. Configure appropriate parameters for the operation

For additional information refer to esri documentation for [map services](https://developers.arcgis.com/rest/services-reference/enterprise/query-map-service-layer/) and [feature services](https://developers.arcgis.com/rest/services-reference/enterprise/feature-service/).

### WMS (Web Map Service)
**WMS Request:**
1. Set service type to "WMS"
2. Ensure the url ends with /wms or includes ?SERVICE=WMS
3. Send request to view available layers
4. The GetCapabilities is called to identify layers
5. Layers are listed for you to select which ones should be added to the Map
6. Select the layers and click add to map.

### WFS (Web Feature Service)
**WFS Request:**
1. Set service type to "WFS"
2. Ensure the url ends with /wfs
3. All Layers will be added to the map and layer list

## Map Visualization
When your request returns spatial data:
1. **Check** the Layers tab in the response
2. **Select** layers to add to the map
3. **View** the data in the right panel map viewer
4. **Interact** with features:
   - Click features for attribute popup
   - Pan and zoom to explore
   - Use map controls for navigation

### Map Controls
- **Zoom in/out**: Mouse wheel or +/- buttons
- **Pan**: Click and drag
- **Feature info**: Click on map features