Requests Overview

The VBAPI is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Authorization Headers

There are three tyes of authentication schemes in VBAPIs.

1. API Keys: All endpoints require your assigned VBA API Key in the x-api-key header. Ex: Header: x-api-key' Value: (api-key)`
2. Basic Authentication: Some endpoints require basic authentication in the form of bas64 encoded username:password in the Authorization header. Ex: Header: Authorization Value: Basic (base64 encoded username:password)
3. Bearer Authentication: After successful user login, a JWT token is returned. The ID Token in this response can be passed in the Authorization header as a Bearer token. Ex: Header: Authorization Bearer (id-token)

Semantics of HTTP Methods Used

Idempotent Requests

Idempotency is important in APIs because a resource may be called multiple times if the network is interrupted. In this scenario, non-idempotent operations can cause significant unintended side-effects by creating additional resources or changing them unexpectedly. VBAPI uses an idempotent endpoint strategy where applicable such that identical requests can be made once or several times in a row with the same effect while leaving the server in the same state.

POST

• Not idempotent!
  • Multiple POST requests on /employees lead to many new different employees (that’s why POST is not idempotent).
• Used for creating
  • Example: POST /employees creates a new employee. The newly created employee is returned in the response payload.
• Successful HTTP Code is 201.
  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. GET never changes the state of the resource on the server-side. It must not have side-effects.
• Hence, the response can be cached safely.
• Examples:
  • GET /employees - Lists all employees
  • GET /employees/1 - Shows the details of the employee 1
• Successful HTTP Code is 200.
  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
• Can be used for full updates ONLY.
  • Example: PUT /employees/1 - updates employee 1
• Always include the whole payload in the request. It’s all or nothing.
• Successful HTTP Code is 200.
  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
• See PUT for updates.

DELETE

• Idempotent
• Used for deletion.
• Example: DELETE /employees/1 deletes employee 1
• Successful HTTP Code is 204.
  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

• Updates are Idempotent. Creates are not.
• Can be used for both creating and updating!
• Send an array of objects. Items with keys defined will attempt an Update; items without keys defined will attempt a create.
• Successful HTTP Code is 207
  • Response payload will contian the individual response codes for each item (eg, 200 for update, 201 for create, 4xx/5xx for errors).
  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);