Documentation around response shapes

[jbccollins]

Hello,

Not sure if this is the right place to ask this question so please let me know if there is a better place to discuss this.

Looking at the swagger json that is embedded into api.congress.gov, there does not seem to be anything there (or anywhere online that I can find) that describes the response shape for each endpoint.

I've been going through each endpoint and writing my own custom types for these in TypeScript. For example for the /bill endpoint I have this type:

export interface BillListAll_BillsItem {
  congress: number;
  latestAction: Action;
  number: string;
  originChamber: Chamber;
  originChamberCode: ChamberCode;
  title: string;
  type: BillType;
  updateDate: string;
  updateDateIncludingText: string;
  url: string;
}

I'm hoping that there might be some documentation somewhere that would make this process easier to do. Right now I am manually hitting each endpoint which is a very manual "try and see what happens" type of process.

[Gmanicus]

I've done this in the past. If you open up the Swagger documentation UI, go to the developer console, and copy the response from ui.getConfigs() into a tool like https://github.com/RicoSuter/NSwag, it can generate a Typescript client API for you. Otherwise, you should also be able to paste JSON as types in VS Code, for instance.

The response schemas are also described in https://github.com/LibraryOfCongress/api.congress.gov/tree/main/Documentation

[jbccollins]

The response schemas are what I'm looking for thanks :)

I did initially use a tool to generate an API client from the swagger json. The issue was that the client only typed the requests, not the responses. And I think that's because the swagger json does not contain any structured information about the response shape for each endpoint. In order to achieve that I think I still need to manually write my own custom client. I need to look at the .md files you linked which seem to be very helpful :) Looks like they call out which fields are "optional" too which is really nice.

Edit:

Given that I'm already going to be doing this for my own TypeScript client... would the maintainers of this repository be open to me submitting pull requests for changing the underlying swagger json? I'm thinking I could flesh out the responses field for each request defined in the swagger json so that it accurately describes the response shape. Looking at this swagger documentation as a reference: https://swagger.io/docs/specification/v3_0/describing-responses/#response-body

By doing that, anyone could generate any type-safe API client in any language.

[apreiter18]

We are currently in the process of updating the swagger.json and will follow up with this when it is completed.