ronydahdal
commented
1 year ago openapi: 3.0.0
info:
title: Buildings
description: This API returns building information for Elon University.
version: 1.0.0
paths:
/mcewen:
tags:
- mcewen
get:
summary: Gets information about McEwen
description: Retrieves available data abt McEwen like floors and address
responses:
"200":
description: OK
"404":
description: Invalid
/powell:
tags:
- powell
get:
summary: Gets information about Powell
description: Retrieves available data abt Powell like floors and address
responses:
"200":
description: "OK"
"404":
description: "Invalid" 
jumarmartin
We've already have some code down for the building API but we do not have a specification down for consumers to utilize in the future in understanding what is possible with the current API.
In most industry projects, APIs are defined by a specification called OpenAPI, usually it's second version. As OpenAPI is the standard, we'll naturally be formalizing our proof-of-concept in it and publishing it somewhere for consumption.
When specifying an API, one must have an understanding of the flow of data from the user to the service and back. In this case, we have a user, our service, and an external service in the name of Elon's API that we're brokering. The specification linked above is it from first principles but here are some resources to help define this and use Insomnia's "Design Document" feature to guide the process.
Resources: