search

doner-kebard / card-game-backend

Backend for Döner Kebard's first (yet unnamed) card game
MIT License
1 stars 0 forks source link

API Documentation #5

Open kenan-rhoton opened 6 years ago

kenan-rhoton commented 6 years ago

Description of the current situation Right now, anyone trying to work with the front-end part will have to annoy the back guys or know clojure and the back-end project itself just to know the endpoints and responses

Description of the wanted situation A Documentation page/s of the endpoints, http methods that accepts and the possible responses and a brief description if it's not evident

A good API should indicate:

  1. What endpoints the API responds to (POST /games/, GET /games/:game-id/player/:player-id, etc.)
  2. The accepted formats for the request
  3. The response format

All formats should be annotated with the types of the data, as well as conditions that need to hold.

However, if we truly implement Pact, the Contract will be the best documentation, and we might even be able to just generate the documentation from there.

Masclins commented 5 years ago

Where should it be? On docs/?

kenan-rhoton commented 5 years ago

yes, it should be in docs/