Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
executable file 192 lines (173 sloc) 10.5 KB
# API documentation
# This is mean to be a working demo of a suggested prototype for API documentation at the VA.
# This is a forkable, cloneable, OpenAPI driven documentation for any API developer to use.
# All the instructions for minimum viable API documentation is present here in this _congif.yml
# Providing a checlist that developers can apply as they are preparing their APIs for consumption.
# This project is NOT maintained by the VA
# This project is maintained by Kin Lane (@kinlane)
# Submit a GitHub Issue or Email me if you have questions.
# Overview of This API
# Please provide a title, description, and the URL for this APIs landing page.
title: VA Digital | API Platform Management
description: This is a demo portal to show what is possible with API document at the Department of Veterans Affairs (VA).
url: https://va-working.github.io/api-documentation/
# GitHub
# Please make sure and update which organization this API is in, and the name of the repository.
github_org: va-working
github_repo: api-documentation
# Navigation
# This is where you can adjust the links that show in the main Navigation
navigation:
- label: Documentation
url: https://developer.va.gov/explore
- label: Benefits
url: https://developer.va.gov/explore/benefits
- label: Facilities
url: https://developer.va.gov/explore/facilities
- label: Health
url: https://developer.va.gov/explore/health
- label: Verification
url: https://developer.va.gov/explore/verification
footer_navigation:
- label: Micro-consulting
url: https://github.com/department-of-veterans-affairs/VA-Micropurchase-Repo
- label: Accessibility
url: https://www.section508.va.gov/
- label: Web Policies
url: https://www.va.gov/webpolicylinks.asp
- label: Privacy
url: https://www.va.gov/privacy/
# Background
# Please provide some background for this API, helping consumers understand it's history.
background_title: Background
background_details: This API provides information about physical VA facilities. Information available includes geographic location, address, phone, hours of operation, and available services.<br /><br />VA operates several different types of facilities, the types represented in this API include:<ul><li>Health facilities</li><li>Benefits facilities</li><li>Cemeteries</li><li>Vet Centers</li></ul>
# Authentication
# Provide an overview of what it takes to authenticate with the API using header APIkey, basic auth, or OAuth
authentication_title: Authentication
authentication_detail: All API requests require that you pass along a token you receive after signing up and being approved, including it as an HTTP header with name "apikey".
# Response Formats
# Prove a list of the media types available for responses.
# Make sure these media types are reflected in the OpenAPI definition for this API.
response_formats_title: Response Formats
response_formats_header: Clients may request several response formats by setting the `Accept` header.
response_formats:
- name: application/json
details: The default JSON response format complies with JSON API.
url: https://tools.ietf.org/html/rfc8259
- name: application/geo+json
details: GeoJSON-compliant format, representing each facility as a Feature with a Point geometry.
url: https://tools.ietf.org/html/rfc7946
- name: text/csv
details: Available for the bulk download operation only.
url: https://tools.ietf.org/html/rfc4180
response_formats_footer: There will be loss of some data when a API consumer switches between each response format.
# Response Elements
# Provide information regarding any other details API consumers should expect when making calls to the API.
response_elements_title: Response Elements
response_elements_header: Some data elements within the response are only present for facilities of a given type.
response_elements:
- The patient satisfaction scores contained in the `satisfaction` element are only applicable to VA health facilities.
- The patient wait time values contained in the `wait_times` element are only applicable to VA health facilities.
- The list of available services in the `services` element is only applicable to VA health and benefits facilities.
response_formats_footer: Depending on the API request made, you can expect different results with your API response.
# Documentation
# Please explain what documentation is available for this individual API.
documentation_title: VA Facilities API Documentation
documentation_details: This is the interactive documentation for the VA Facilities API, providing a hands-on way to explore what is possible when makng requests to the API, and what to expect with responses. This documentation is driven by the OpenAPI specification, which provides a machine readable contract for the VA Facilities API.
# Definitions
# Please provide an over of how these API definitions can be used.
definition_title: Definitions
definition_header: We provide machine readable definitions for our APIs, allowing you to import into the service or tooling of your choice.
definition_footer: Feel free to submit a pull request for these API definitions using GitHub, or submit an issue when you see something incomplete.
# OpenAPI
# Please provide a complete OpenAPI definition describing the surface area of the API.
# Including info, tags, servers, paths, as well as securitySchemes, schemas for all definitions, and error objects
# PUblish the OpenAPI definition to the root of the GitHub repository for this API.
openapi_url: https://va-working.github.io/api-documentation/openapi.json
# Postman FeatureCollection
# Please take the OpenAPI specification and import into Postman, then export a Postman collection.
# Publish the Postman Collection in the root of this APIs GitHub repository.
postman_collection_url: https://va-working.github.io/api-documentation/postman.json
# Support
# Please make sure an provide at least one suppor channel for this project.
# Making sure it is always being supported, and is never abandoned.
support_title: Support
support_header: We provide three ways in which you can receive support for this API, and have your questions answered as you are working to integrate it into your web or mobile application.
support_channels:
- details: GitHub Issue
image: https://va-working.github.io/api-documentation/images/github.png
url: https://github.com/va-working/api-documentation/issues
- details: Twitter
image: https://va-working.github.io/api-documentation/images/twitter.png
url: https://twitter.com/apievangelist
- details: Email
image: https://va-working.github.io/api-documentation/images/email.png
url: mailto%3A info@apievangelist.com
support_footer: If your question is of the private nature please email us, for all other inquires please submit as GitHub issue if possible, so that others can learn from your question to.
# Road Map
# Please provide insight into the road map of this API.
# Allowing API consumers to understand what is coming.
# While also able to understand what has happened in the past.
road_map_title: Road Map
road_map_header: This is where we provdie insight into what the future holds for this API, what current issues we are working on, and what has changed in the past work on this API.
road_map_entries:
- title: Road Map Entry
date: 2018/10/20
details: These are the details for this road map entry, explaining what it is all about.
url: https://github.com/va-working/api-documentation/issues/1
- title: Road Map Entry
date: 2018/10/20
url: https://github.com/va-working/api-documentation/issues/1
details: These are the details for this road map entry, explaining what it is all about.
- title: Road Map Entry
date: 2018/10/20
url: https://github.com/va-working/api-documentation/issues/1
details: These are the details for this road map entry, explaining what it is all about.
issue_entries:
- title: Issue Entry
date: 2018/09/10
details: These are the details for this road map entry, explaining what it is all about.
url: https://github.com/va-working/api-documentation/issues/3
change_log_entries:
- title: Change Log Entry
date: 2017/10/20
details: These are the details for this road map entry, explaining what it is all about.
url: https://github.com/va-working/api-documentation/issues/2
- title: Change Log Entry
date: 2017/10/20
details: These are the details for this road map entry, explaining what it is all about.
url: https://github.com/va-working/api-documentation/issues/2
- title: Change Log Entry
date: 2017/10/20
details: These are the details for this road map entry, explaining what it is all about.
url: https://github.com/va-working/api-documentation/issues/2
road_map_footer: You can submit a road map suggestion, or inform us of an issuing using one of the support channels listed above, and we will tag and consider for inclusion here.
# Reference
# Please provide any references that are relevant to this API and consumers.
reference_title: References
reference_details: These are some relevant links regarding the use of this API, and the standards it supports.
references:
- name: GeoJSON Format
details: GeoJSON is a format for encoding a variety of geographic data structures.
url: https://tools.ietf.org/html/rfc7946
- name: JSON API Format
details: JSON API the specification we use for how a client should request that resources be fetched or modified, and how a server should respond to those requests.
url: http://jsonapi.org/format/
- name: OpenAPI
details: The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.
url: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md
- name: Postman Collections
details: Postman Collections are machine readable formats of saved API requests you can organize into folders, and use in the Postman client.
url: https://www.getpostman.com/docs/v6/postman/collections/creating_collections
# Customize
# You can customize this project as much as you'd like.
# Add and remove leements on the index.html page of the site.
# Try to add new elements here as YAML parameters and objecs.
# Then add them dynamically to the web page of the site.
# Keeping everything as dynamic, and centrally driven as possible.
# General Jekyll Site Settings
markdown: kramdown
permalink: pretty
pygments: true
highlighter: rouge
exclude: [".rvmrc", ".rbenv-version", "README.md", "Rakefile", "changelog.md",".DS_Store"]