# VBAPI Orientation VBAPI is a powerful solution designed for clients utilizing VBASoftware. Traditionally, clients have had read-only access to their databases. With VBAPI, organizations can directly interact with their production database, enabling seamless integration with internal and external systems. By leveraging VBAPI, companies can operate more autonomously and reduce reliance on VBA for vendor interfaces or custom solution development. ## Types of Endpoints ### Data Access Endpoints These endpoints allow retrieval and manipulation of structured data within VBASoftware. Each database table corresponds to multiple API endpoints supporting standard CRUD operations: - **Create** – Insert new records. - **List** – Retrieve multiple records. - **Get** – Fetch a specific record. - **Update** – Modify existing data. - **Delete** – Remove records. - **Batch Operations** – Process multiple records in a single request. ### Advanced Endpoints Advanced endpoints go beyond basic CRUD data access. The Advanced APIs contain additional business logic and perform complex tasks. Some examples are: - **Adjudicating a Claim** - **Disenrolling a Member** # Request Handling ## Overview The VBAPI follows the [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) 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: ``` x-api-key: (your_api_key) ``` 2. **Basic Authentication**: Some endpoints require base64-encoded `username:password` in the `Authorization` header. Example: ``` 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: ``` 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 ```javascript 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 ```javascript 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 ```javascript 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 ```javascript 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 ```javascript 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); ``` # API Response Handling ## HTTP Response Codes VBAPI adheres to conventional HTTP response codes to indicate the success or failure of an API request. ### Success Responses (`2xx`) - **200 OK** – The request was successful, and the response contains the requested data. - **201 Created** – The request successfully created a resource. ### Client Errors (`4xx`) - **400 Bad Request** – The request was malformed or invalid. - **401 Unauthorized** – Authentication is required or failed. - **403 Forbidden** – The authenticated user lacks necessary permissions. - **404 Not Found** – The requested resource does not exist. ### Server Errors (`5xx`) - **500 Internal Server Error** – A generic server error occurred. ## Response Payload Structure Every response from VBAPI follows a standardized envelope format, ensuring consistency across successful and error responses. ```json { "data": single object | array of objects | null on error, "error": single object | null, "debug": { "activityId": "unique request identifier" } } ``` ### Data Object Successful responses include a `data` field, which contains either a single object or an array of objects. The `error` field remains `null`, and the `debug` object contains an `activityId`. #### Example: ```json { "data": [ { "id": 1, "name": "Example" } ], "error": null, "debug": { "activityId": "a62d1412-9fe9-4ac0-9dc7-3a3e35d202fd" } } ``` ### Error Object If an error occurs, the `data` field is `null`, and an `error` object provides details. The `debug` object still contains an `activityId`. #### Error Object Fields: - **type** – A URL linking to additional information about the error. - **title** – A brief, user-friendly summary of the error. - **status** – The HTTP status code corresponding to the error. - **detail** – A descriptive message explaining the error. - **instance** – The specific API endpoint where the error occurred. #### Example: ```json { "data": null, "error": { "type": "https://httpstatuses.com/404", "title": "Not Found", "status": 404, "detail": "The requested resource (xyz) was not found.", "instance": "/clients/abc/products/xyz" }, "debug": { "activityId": "a62d1412-9fe9-4ac0-9dc7-3a3e35d202fd" } } ``` ### Debug Object Each response includes a `debug` object containing a unique `activityId`. This identifier links all internal logs related to a specific request. When seeking support, providing the `activityId` ensures the fastest resolution. By structuring responses in this format, VBAPI ensures consistency, traceability, and ease of troubleshooting for developers.