Proposal for more idiomatic REST API

[caguado]

Hi folks,

As we spoke at NANOG 88 about ramping up efforts and I proposed to heighten the API model using a more idiomatic approach to REST verbs, types, error handling, pagination, etc, I would like to come back now at it that I found some time to work on it.

I have re-modeled with a focus on adding resources, following REST conventions around the verbs, adding types for the resource representations. I'm also adding a general pagination mechanism so that we bound the latency of the API on potentially large payloads early on.

I helped myself with Smithy, Amazon's Interface Description Language, to do this semantic remodelling although is not required for clients or servers.

It may be a rather large pull request so I would like to gather your inputs on how you think about this whole exercise and whether I should create smaller PRs that stand by themselves by remain aligned to the leitmotiv of this effort, or you prefer a single-commit review.

My playground is in the orphan branch below:
https://github.com/caguado/autopeer-smithy/tree/feature/smithy-model

[grizz]

Thanks, will check it out ASAP.