Request Handling

Overview

The VBAPI follows the REST architecture, offering predictable resource-oriented URLs, JSON-encoded request bodies, JSON-encoded responses, and standard HTTP methods and response codes. All API requests must be made over HTTPS; plain HTTP requests will be rejected.

Required Headers

User-Agent Header

Every request must include a User-Agent header. Best practice is to provide your company's use case information within this header to help us optimize API performance and usage analytics.

Authorization Headers

VBAPI supports three authentication schemes:

  1. API Keys : All endpoints require an API key in the x-api-key header. Example:
    Copy
    Copied
    x-api-key: (your_api_key)
  2. Basic Authentication : Some endpoints require base64-encoded username:password in the Authorization header. Example:
    Copy
    Copied
    Authorization: Basic (base64_encoded_username:password)
  3. Bearer Authentication : Upon successful login, a JWT token is issued. Include it in the Authorization header for subsequent requests. Example:
    Copy
    Copied
    Authorization: Bearer (id_token)
attention

Contact your Account Executive to request an API Key.

HTTP Methods and Idempotency

Idempotent Requests

Idempotency ensures that repeated identical requests result in the same outcome, preventing unintended side effects.

POST

  • Not idempotent
  • Used for creating new resources
  • Returns 201 Created on success
Copy
Copied
const resp = await fetch('https://vbapi-dev.vbasoftware.com/vbasoftware/counties', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    },
    body: JSON.stringify({
        county_Code: 'string',
        county_Name: 'string',
        state: 'st'
    })
});
const data = await resp.json();
console.log(data);

GET

  • Idempotent
  • Read-only operation with no side effects
  • Responses can be cached
  • Returns 200 OK on success
Copy
Copied
const countyCode = 'YOUR_countyCode_PARAMETER';
const resp = await fetch(`https://vbapi-dev.vbasoftware.com/vbasoftware/counties/${countyCode}`, {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    }
});
const data = await resp.text();
console.log(data);

PUT

  • Idempotent
  • Used for full updates (all-or-nothing updates)
  • Returns 200 OK on success
Copy
Copied
const countyCode = 'YOUR_countyCode_PARAMETER';
const resp = await fetch(`https://vbapi-dev.vbasoftware.com/vbasoftware/counties/${countyCode}`, {
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    },
    body: JSON.stringify({
        county_Code: 'ONE',
        county_Name: 'County UNO',
        state: 'SC'
    })
});
const data = await resp.json();
console.log(data);

PATCH

  • Not supported
  • Use PUT for updates

DELETE

  • Idempotent
  • Used to delete resources
  • Returns 204 No Content on success
Copy
Copied
const countyCode = 'YOUR_countyCode_PARAMETER';
const resp = await fetch(`https://vbapi-dev.vbasoftware.com/vbasoftware/${countyCode}`, {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    }
});
const data = await resp.text();
console.log(data);

BATCH PUT

  • Idempotent for updates, non-idempotent for creates
  • Supports bulk create and update operations
  • Returns 207 Multi-Status , with individual response codes for each item
Copy
Copied
const resp = await fetch(`https://vbapi-dev.vbasoftware.com/vbasoftware/counties-batch`, {
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    },
    body: JSON.stringify([
        {
            county_Code: 'ONE',
            county_Name: 'County One',
            state: 'SC'
        },
        {
            county_Code: 'TWO',
            county_Name: 'County Two',
            state: 'SC'
        }
    ])
});
const data = await resp.json();
console.log(data);

By following these guidelines, you ensure efficient and reliable interaction with VBAPI.