API response types/schema/documentation?

[Josh-Cena]

CourseTable here :)

I find that we are lacking any documentation about what shape the API responses are in. At least I didn't discover them easily on https://yalies.io/apidocs. It merely says:

The endpoint returns a JSON list of yale personnel.

And that:

Most properties can be filtered by, including netid, upi, email, mailbox, phone, title, first_name, preferred_name, middle_name, last_name, suffix, pronoun, school_code, school, year, curriculum, college, college_code, leave, birthday, residence, building_code, entryway, floor, suite, room, major, access_code, organization_code, organization, unit_class, unit_code, unit, office_building, and office_room.

However, there's no exhaustive list of attributes and their shapes! For example, what valid school_codes are there?

I request one of the three, but preferably all of them:

1. TypeScript type defs to be published with https://github.com/Yalies/js-yalies (cooler if you author it in TS)
2. JSON schema describing the API, either published with js-yalies, or published on the website available for external fetching
3. Detailed documentation of response and request parameter shapes. See also https://github.com/Yalies/api/issues/31

These should help foster a helpful developer community. Thanks!

[bearsyankees]

+1 :)

[ErikBoesen]

Hey folks, this is definitely something that we should add. For now, you can query the endpoint /filters and it will give you a JSON list of options for the non-open-ended fields. I'll see if I can find someone to put this, and more explicit documentation of the responses, into the docs.