如何定义API端点

Question

I am designing an API to request information on an index with data that respect a certain JSON format.

For the moment I only have data with type building, but other type could be coming, ie.: :

example data #1 :
"type": "building",
"id": "1",
"address" : "1 test",
...
"buildingType": "private",
"buildingSubType: "house"

example data #2 :
"type": "building",
"id": "2",
"address" : "100 test",
...
"buildingType": "corporate",
"buildingSubType: "restaurant"

example data #3 :
"type": "building",
"id": "3",
"address" : "200 test",
...
"buildingType": "government",
"buildingSubType: "hr services"

When I began the data was simpler with less types and subtypes so building the API endpoints was simple, but with time comes complexity and I want to define my api to be the more futureproof in regards to new data coming

In respect to REST and future API Documentation here is what I got and would like to validate :

/buildings - Returns all buildings entries
/buildings/{id} - Returns a specific building entry
/buildings/buildingTypes - Returns all buildingTypes
/buildings/buildingTypes/{name} - Returns building entries with the specified buildingType
/buildings/buildingTypes/{name}/buildingSubTypes - Returns all buildingSubTypes for the specified buildingType
/buildings/buildingTypes/{name}/buildingSubTypes/{name} - Returns building entries with the specified buildingType and buildingSubType

For 2 I will add query-string parameters to filter more precisely like : /buildings/buildingTypes/corporate?states=NY /buildings/buildingTypes/corporate/buildingSubTypes/restaurant?state=NY

Answer 1

In respect to REST and future API Documentation here is what I got and would like to validate

REST doesn't care what spellings you use for your URLs, or how you organize your hierarchy of resources.

URL spelling conventions are for human convenience only -- they are no more important to the correctness of an API than the spelling of variable names.