Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
executable file 896 lines (895 sloc) 31.1 KB
{
"openapi": "3.0.0",
"info": {
"version": "0.0.1",
"title": "Sample Documentation - VA Facilities",
"description": "<p>This is a sample API documentation and GitHub repository to demonstrate one possible minimum viable API documentation for any new or existing HTTP API. It can be forked and use for any API you are developing. To update this documentation after forking, all you have to do is publish either a JSON or YAML OpenAPI (fka Swagger) definition into the /openapi folder for this repo, and update the path in the index.html fo the project.</p><p>Make sure that you provide a complete (enough) OpenAPI definition with all of the following:</p><ul><li><strong>Title and Description</strong> - Provide the concise description of what an API does from the README, and make sure it is based into the APIs definition.</li><li><strong>Base URL</strong> - Have the base URL, or variable representation for a base URL present in API definitions.</li><li><strong>Base Path</strong> - Provide any base path that is constant across paths available for any single API.</li><li><strong>Content Types</strong> - List what content types an API accepts and returns as part of its operations.</li><li><strong>Paths</strong> - List all available paths for an API, with summary and descriptions, making sure the entire surface area of an API is documented.</li><li><strong>Parameters</strong> - Provide details on the header, path, and query parameters used for API path being documented.</li><li><strong>Body</strong> - Provide details on the schema for the body of each API path that accepts a body as part of its operations.</li><li><strong>Responses</strong> - Provide HTTP status code and reference to the schema being returned for each path.</li><li><strong>Examples</strong> - Provide example requests and response for each API path being documented.</li><li><strong>Schema</strong> - Document all schema being used as part of requests and responses for all APIs paths being documented.</li><li><strong>Authentication</strong> - Document the authentication method used (ie. Basic Auth, Keys, OAuth, JWT).</li><li><strong>Contact</strong> - Provide a contact for the API, who is responsible for the feedback loop surrounding the API..</li></ul><p>Once you fork this repository, you will need to enable the GitHub Pages for the site under the repository settings before you are give a URL to view your API documentation. This documentation site uses OpenAPI 3.0 for the core contract, and Swagger UI for the documentation.</p><p>This is just a sample of one possible API documentation the VA, or any other federal agency could provide as a default template for API providers to use when developing their API. Providing usable guidance regarding the documentation that should exist for ALL APIs.</p><p>You can <a href='https://github.com/va-working/openapi-documentation'>fork this project at GitHub.</a>, and if you have any questions you can submit an issue for the project via its GitHub repository.",
"termsOfService": "",
"contact": {
"name": "developer.va.gov"
}
},
"tags": [
{
"name": "facilities",
"description": "VA Facilities API"
}
],
"servers": [
{
"url": "https://dev-api.vets.gov/services/va_facilities/{version}",
"description": "Vets.gov API development environment",
"variables": {
"version": {
"default": "v0"
}
}
}
],
"paths": {
"/facilities": {
"get": {
"tags": [
"facilities"
],
"summary": "Query facilities based on a geographic bounding box and optional attribute filters",
"description": "Retrieve all facilities contained within the specified bounding box. Bounding box is \nspecified as four parameters long1, lat1, long2, lat2. Relative ordering of longitude and \nlatitude parameters is unimportant. \n\nAdditionally one can filter the facilities within the bounding box by type and available\nservices. Only facilities of type \"health\" and \"benefits\" may be filtered by available\nservices.\n\nResults of this operation are paginated. JSON responses include pagination information\nin the standard JSON API \"links\" and \"meta\" elements. GeoJSON responses include pagination\ninformation in the \"Link\" header.\n",
"operationId": "getFacilitiesByLocation",
"security": [
{
"api_key": []
}
],
"parameters": [
{
"name": "bbox[]",
"description": "Bounding longitude/latitude/longitude/latitude within which facilities will be returned. \nBounding box parameters should be specified in WGS84 coordinate reference system.\n",
"in": "query",
"required": true,
"x-style": "form",
"x-exploded": true,
"schema": {
"type": "array",
"minItems": 4,
"maxItems": 4,
"items": {
"type": "number",
"format": "float"
}
}
},
{
"name": "type",
"description": "Optional facility type search filter",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"health",
"cemetery",
"benefits",
"vet_center"
]
}
},
{
"name": "services[]",
"description": "Optional facility service search filter",
"in": "query",
"x-style": "form",
"x-exploded": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "page",
"description": "Page of results to return per paginated response.",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"description": "Number of results to return per paginated response.",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 20
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Facility"
}
}
}
}
},
"application/vnd.geo+json": {
"schema": {
"required": [
"type",
"features"
],
"properties": {
"type": {
"type": "string",
"enum": [
"FeatureCollection"
]
},
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FacilityFeature"
}
}
}
}
}
},
"headers": {
"Link": {
"description": "GitHub-style pagination information. Only present for GeoJSON-format responses.",
"schema": {
"type": "string",
"example": "<https://dev-api.vets.gov/services/va_facilities/v0/facilities?bbox%5B%5D=-120&bbox%5B%5D=40&bbox%5B%5D=-125&bbox%5B%5D=50&page=2&per_page=20>; rel=\"self\", <https://dev-api.vets.gov/services/va_facilities/v0/facilities?bbox%5B%5D=-120&bbox%5B%5D=40&bbox%5B%5D=-125&bbox%5B%5D=50&page=1&per_page=20>; rel=\"first\", <https://dev-api.vets.gov/services/va_facilities/v0/facilities?bbox%5B%5D=-120&bbox%5B%5D=40&bbox%5B%5D=-125&bbox%5B%5D=50&page=1&per_page=20>; rel=\"prev\", <https://dev-api.vets.gov/services/va_facilities/v0/facilities?bbox%5B%5D=-120&bbox%5B%5D=40&bbox%5B%5D=-125&bbox%5B%5D=50&page=3&per_page=20>; rel=\"next\", <https://dev-api.vets.gov/services/va_facilities/v0/facilities?bbox%5B%5D=-120&bbox%5B%5D=40&bbox%5B%5D=-125&bbox%5B%5D=50&page=5&per_page=20>; rel=\"last\""
}
}
}
},
"401": {
"description": "Missing API token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthorizationError"
}
}
}
},
"403": {
"description": "Invalid API token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthorizationError"
}
}
}
},
"406": {
"description": "Requested format unacceptable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
}
}
}
},
"/facilities/{id}": {
"get": {
"tags": [
"facilities"
],
"summary": "Retrieve a specific facility by ID",
"operationId": "getFacilityById",
"security": [
{
"api_key": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"description": "Facility ID, in the form `<prefix>_<id>`, where prefix is one of \"vha\", \"vba\", \"nca\", or \"vc\" \nfor health, benefits, cemetery, or Vet Center facilities respectively. \n",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"required": [
"data"
],
"properties": {
"data": {
"$ref": "#/components/schemas/Facility"
}
}
}
},
"application/vnd.geo+json": {
"schema": {
"$ref": "#/components/schemas/FacilityFeature"
}
}
}
},
"400": {
"description": "Bad request - invalid or missing query parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
},
"401": {
"description": "Missing API token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthorizationError"
}
}
}
},
"403": {
"description": "Invalid API token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthorizationError"
}
}
}
},
"404": {
"description": "Facility not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
},
"406": {
"description": "Requested format unacceptable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
}
}
}
},
"/facilities/all": {
"get": {
"tags": [
"facilities"
],
"summary": "Bulk download of all available facilities",
"description": "Retrieve all available facilities in a single operation, formatted as either a GeoJSON \nFeatureCollection or as a CSV. Due to the complexity of the facility resource type, the CSV\nresponse contains a subset of available facility data - specifically it omits the \navailable services, patient satisfaction, and patient wait time data. \n",
"operationId": "getAllFacilities",
"security": [
{
"api_key": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Success",
"content": {
"application/vnd.geo+json": {
"schema": {
"required": [
"type",
"features"
],
"properties": {
"type": {
"type": "string",
"enum": [
"FeatureCollection"
]
},
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FacilityFeature"
}
}
}
}
},
"text/csv": {
"schema": {
"type": "string",
"example": "id,name,station_id,latitude,longitude,facility_type,classification,website,physical_address_1,physical_address_2,physical_address_3,physical_city,physical_state,physical_zip,mailing_address_1,mailing_address_2,mailing_address_3,mailing_city,mailing_state,mailing_zip,phone_main,phone_fax,phone_mental_health_clinic,phone_pharmacy,phone_after_hours,phone_patient_advocate,phone_enrollment_coordinator,hours_monday,hours_tuesay,hours_wednesday,hours_thursday,hours_friday,hours_saturday,hours_sunday\nvc_0101V,Boston Vet Center,0101V,42.3445959000001,-71.0361051099999,vet_center,,,7 Drydock Avenue,Suite 2070,,Boston,MA,02210,,,,,,,857-203-6461 x,,,,,,,800AM-700PM,800AM-800PM,800AM-700PM,800AM-800PM,800AM-600PM,-,-\nvba_362b,Houston Regional Benefit Office at Frank Tejeda Outpatient Clinic,362b,29.51690196,-98.59601936,va_benefits_facility,Outbased,NULL,5788 Eckhert Road,,,San Antonio,TX,78240,,,,,,,210-699-5040,210-699-5079,,,,,,,,,,,,\nvha_402GC,Rumford VA Clinic,402GC,44.55185578,-70.55746856,va_health_facility,Primary Care CBOC,http://www.maine.va.gov/locations/rumford.asp,431 Franklin Street,,,Rumford,ME,04276-2100,,,,,,,207-369-3200 x,207-369-3277 x,207-369-3200 x 3200,207-623-8411 x5770,866-757-7503 x,207-623-5760 x,207-626-4743 x,,,,,,,\nnca_800,Alton National Cemetery,800,38.8905166870001,-90.1630421139999,va_cemetery,National Cemetery,https://www.cem.va.gov/cems/nchp/alton.asp,600 Pearl St,,,Alton,IL,62002,2900 Sheridan Rd,,,St. Louis,MO,63125,314-845-8320,314-845-8355,,,,,,,,,,,,\n"
}
}
}
},
"401": {
"description": "Missing API token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthorizationError"
}
}
}
},
"403": {
"description": "Invalid API token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthorizationError"
}
}
}
},
"406": {
"description": "Requested format unacceptable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"api_key": {
"type": "apiKey",
"name": "apikey",
"in": "header"
}
},
"schemas": {
"Facility": {
"description": "JSON API-compliant object describing a VA facility",
"type": "object",
"required": [
"id",
"type",
"attributes"
],
"properties": {
"id": {
"type": "string",
"example": "vha_688"
},
"type": {
"type": "string",
"enum": [
"va_facilities"
]
},
"attributes": {
"type": "object",
"required": [
"name",
"facility_type",
"lat",
"long"
],
"properties": {
"name": {
"type": "string",
"example": "Washington VA Medical Center"
},
"facility_type": {
"type": "string",
"enum": [
"va_health_facility",
"va_benefits_facility",
"va_cemetery",
"vet_center"
]
},
"classification": {
"type": "string",
"example": "VA Medical Center (VAMC)"
},
"lat": {
"description": "Facility latitude",
"type": "number",
"format": "float",
"example": 38.9311137
},
"long": {
"description": "Facility longitude",
"type": "number",
"format": "float",
"example": -77.0109110499999
},
"website": {
"type": "string",
"format": "url",
"example": "http://www.washingtondc.va.gov"
},
"address": {
"type": "object",
"properties": {
"mailing": {
"$ref": "#/components/schemas/Address"
},
"physical": {
"$ref": "#/components/schemas/Address"
}
}
},
"phone": {
"$ref": "#/components/schemas/PhoneNumbers"
},
"hours": {
"$ref": "#/components/schemas/Hours"
},
"services": {
"type": "object",
"properties": {
"other": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Online Scheduling"
]
}
},
"health": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HealthService"
}
},
"benefits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BenefitsService"
}
},
"last_updated": {
"type": "string",
"format": "date",
"example": "2018-01-01"
}
}
},
"satisfaction": {
"type": "object",
"properties": {
"health": {
"$ref": "#/components/schemas/PatientSatisfaction"
},
"effective_date": {
"type": "string",
"format": "date",
"example": "2018-01-01"
}
}
},
"wait_times": {
"type": "object",
"properties": {
"health": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PatientWaitTime"
}
},
"effective_date": {
"type": "string",
"format": "date",
"example": "2018-01-01"
}
}
}
}
}
}
},
"FacilityFeature": {
"description": "GeoJSON-complaint Feature object describing a VA Facility",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"Feature"
],
"example": "Feature"
},
"geometry": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"Point"
],
"example": "Point"
},
"coordinates": {
"type": "array",
"minLength": 2,
"maxLength": 2,
"items": {
"type": "number",
"format": "float"
},
"example": [
-77.0367761,
38.9004181
]
}
}
},
"properties": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Washington VA Medical Center"
},
"id": {
"type": "string",
"example": "vha_688"
},
"facility_type": {
"type": "string",
"enum": [
"va_health_facility",
"va_benefits_facility",
"va_cemetery",
"vet_center"
]
},
"classification": {
"type": "string",
"example": "VA Medical Center (VAMC)"
},
"website": {
"type": "string",
"format": "url",
"example": "http://www.washingtondc.va.gov"
},
"address": {
"type": "object",
"properties": {
"mailing": {
"$ref": "#/components/schemas/Address"
},
"physical": {
"$ref": "#/components/schemas/Address"
}
}
},
"phone": {
"$ref": "#/components/schemas/PhoneNumbers"
},
"hours": {
"$ref": "#/components/schemas/Hours"
},
"services": {
"type": "object",
"properties": {
"other": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Online Scheduling"
]
}
},
"health": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HealthService"
}
},
"benefits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BenefitsService"
}
},
"last_updated": {
"type": "string",
"format": "date",
"example": "2018-01-01"
}
}
},
"satisfaction": {
"type": "object",
"properties": {
"health": {
"$ref": "#/components/schemas/PatientSatisfaction"
},
"effective_date": {
"type": "string",
"format": "date",
"example": "2018-01-01"
}
}
},
"wait_times": {
"type": "object",
"properties": {
"health": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PatientWaitTime"
}
},
"effective_date": {
"type": "string",
"format": "date",
"example": "2018-01-01"
}
}
}
}
}
}
},
"Address": {
"type": "object",
"properties": {
"address_1": {
"type": "string",
"example": "50 Irving Street, Northwest"
},
"address_2": {
"type": "string"
},
"address_3": {
"type": "string"
},
"city": {
"type": "string",
"example": "Washington"
},
"state": {
"type": "string",
"example": "DC"
},
"zip": {
"type": "string",
"example": "20422-0001"
}
}
},
"PhoneNumbers": {
"type": "object",
"properties": {
"main": {
"type": "string",
"example": "202-555-1212"
},
"fax": {
"type": "string",
"example": "202-555-1212"
},
"pharmacy": {
"type": "string",
"example": "202-555-1212"
},
"after_hours": {
"type": "string",
"example": "202-555-1212"
},
"patient_advocate": {
"type": "string",
"example": "202-555-1212"
},
"mental_health_clinic": {
"type": "string",
"example": "202-555-1212"
},
"enrollment_coordinator": {
"type": "string",
"example": "202-555-1212"
}
}
},
"Hours": {
"description": "Standard hours of operation. Currently formatted as descriptive text suitable for display, with no guarantee of a standard parseable format. Hours of operation may vary due to holidays or other events.\n",
"type": "object",
"properties": {
"Monday": {
"type": "string",
"example": "9AM-5PM"
},
"Tuesday": {
"type": "string",
"example": "9AM-5PM"
},
"Wednesday": {
"type": "string",
"example": "9AM-5PM"
},
"Thursday": {
"type": "string",
"example": "9AM-5PM"
},
"Friday": {
"type": "string",
"example": "9AM-5PM"
},
"Saturday": {
"type": "string",
"example": "Closed"
},
"Sunday": {
"type": "string",
"example": "Closed"
}
}
},
"HealthService": {
"type": "string",
"enum": [
"PrimaryCare",
"MentalHealthCare",
"UrgentCare",
"EmergencyCare",
"Audiology",
"Cardiology",
"Dermatology",
"Gastroenterology",
"Gynecology",
"Ophthalmology",
"Optometry",
"Orthopedics",
"Urology",
"WomensHealth"
]
},
"BenefitsService": {
"type": "string",
"enum": [
"ApplyingForBenefits",
"BurialClaimAssistance",
"DisabilityClaimAssistance",
"eBenefitsRegistrationAssistance",
"EducationAndCareerCounseling",
"EducationClaimAssistance",
"FamilyMemberClaimAssistance",
"HomelessAssistance",
"InsuranceClaimAssistanceAndFinancialCounseling",
"IntegratedDisabilityEvaluationSystemAssistance",
"Pensions",
"PreDischargeClaimAssistance",
"TransitionAssistance",
"UpdatingDirectDepositInformation",
"VAHomeLoanAssistance",
"VocationalRehabilitationAndEmploymentAssistance"
]
},
"PatientSatisfaction": {
"description": "Veteran-reported satisfaction scores for health care services",
"type": "object",
"properties": {
"primary_care_urgent": {
"type": "number",
"format": "float",
"example": 0.85
},
"primary_care_routine": {
"type": "number",
"format": "float",
"example": 0.85
},
"specialty_care_urgent": {
"type": "number",
"format": "float",
"example": 0.85
},
"specialty_care_routine": {
"type": "number",
"format": "float",
"example": 0.85
}
}
},
"PatientWaitTime": {
"description": "Expected wait times for new and established patients for a given health care service",
"type": "object",
"properties": {
"service": {
"$ref": "#/components/schemas/HealthService"
},
"new": {
"description": "The average number of days a Veteran who hasn’t been to this location has to wait for a non-urgent appointment",
"type": "integer",
"example": 10
},
"established": {
"description": "The average number of days a patient who has already been to this location has to wait for a non-urgent appointment",
"type": "integer",
"example": 5
}
}
},
"APIError": {
"description": "API invocation or processing error",
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"example": "Error title"
},
"detail": {
"type": "string",
"example": "Detailed error message"
},
"code": {
"type": "string",
"example": "103"
},
"status": {
"type": "string",
"example": "400"
}
}
}
}
}
},
"AuthorizationError": {
"description": "API Platform authorization (API token) error",
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "No API key found in request"
}
}
}
}
}
}