- Documentation is clear, if a little poorly formatted.
- Not the biggest fan of the monospace type as body copy.
- I like the queries tab but it's not immediately obvious that it's something that I can interact with.
- Document the data that gets returned!
- Correct types.
- Numbers should be unquoted
- Are all the "note on count/percentage"s the same for every endpoint? If so AND if it's important to have that returned with the API, put it in the heading, not in each object.
- In general, try not to repeat. The wire transfer will be gziped but it's not immediately obvious what's unique per row.
- College scorecard is busted.
- Good job defining the data types. It looks like they follow through in the example returned value but not in the endpoint. Don't quote numbers!
- Can I only filter on onething at a time?
- Hover states make feel like I can click things. Make the examples clickable.
- For filter/join fields, link to definitions/data tables of possible filters (I'm pretty sure that it will never fill the 4,000 length varchar).
I think this was the first API Gray ever asked me to help on?
- I like Swagger. The implementation right now is alright.
- There really is no reason to keep the HTTP status codes.
- Define the data structures that get returned.
- Super minor but I find the click-to-expand very tedious.
- Discoverable API!
- Have resource links embedded in the serialized responses. You have the IDs, just add links.
- Sometimes the embedded serializations don't make a ton of sense. See: tags in social media endpoint.