search

Crisismap / crisismap-backend

API: RESTful data accessor
0 stars 0 forks source link

API endpoints definitions #1

Closed oleksmarkh closed 7 years ago

oleksmarkh commented 7 years ago

(moved from https://github.com/Crisismap/crisismap-data/issues/1)

Categories

GET /api/categories(/:id)

[
  {
    "id": <Number>,
    "name": <String>
  },
  ...
]

Items

GET /api/categories/:category_id/items(/:item_id)

[
  {
    "id": <Number>,
    "title": <String>,
    "description": <String>,
    "geometry": <GeoJSON>
  },
  ...
]

See JSON + GeoJSON specs.

Also, these definitions could be associated with front-end internal data store (see https://github.com/Crisismap/crisismap-frontend/issues/5), though schemas themselves don't have to be coupled (https://github.com/Crisismap/crisismap-frontend/issues/7 is responsible for retrieving and storing this intermediate data).

oleksmarkh commented 7 years ago

question: should we align with some sort of convention? One example: http://zalando.github.io/restful-api-guidelines/naming/Naming.html

zverev commented 7 years ago

I like this convention. As for JSON responses, I suggest using camelCase for all kind of properties.

oleksmarkh commented 7 years ago

suggestion: use Number type for ids

oleksmarkh commented 7 years ago

@zverev , @bkmy43 , guys - let's agree on camelCase vs. snake_case. While Zalando suggests snake_case (probably, because of Python), http://json-schema.org/examples.html suggests camelCase. I'd +1 camelCase - because it's easier to apply a transforming middleware on the back-end rather then injecting that thing into transport layer (or whatever) on the front-end.

bkmy43 commented 7 years ago

I personally would prefer snake, but can live with camelCase as well, if both of you vote for it

oleksmarkh commented 7 years ago

Closing as no objections raised against data structure itself. We assume some metadata to be introduced later on.