search

war-on-ice / woi-api

3 stars 1 forks source link

Documentation for WOI rest endpoints #2

Open pacefalm opened 9 years ago

pacefalm commented 9 years ago

In the spirit of DDD, we need to document what our restful endpoints will be so that we can haggle over best practices, the actual endpoints, and the finer details. I propose we use the Swagger spec language. You can find it at swagger.io, complete with examples, a live demo of their editor and UI, and all kinds of supporting material.

Let's use this issue to decide on the language and list out the specific endpoints we want to support. Let's also prioritize the endpoints to be worked on in chunks that can support specific pages/workflows. Once we come to a consensus, we can split off endpoints into specifc tickets and come up with a workflow around developing those.

pacefalm commented 9 years ago

I believe the strategy here is to tackle the Game summary page first. e.g. http://war-on-ice.com/game1.html?seasongcode=2014201530416

My hunch here is that having one API call that pulls the entire game summary data, and passing it off to whatever templating language we decide on to format is the way to go. Here's how I would organize the endpoints surrounding game summaries

GET /game_summaries/ - return a list of game summaries with some basic information. Would more or less support this page: http://war-on-ice.com/gametable.html

You should also be able to apply filters to this. e.g.

GET /game_summaries/?team=CAR would return a list of Game summaries for the hurricanes.

GET /game_summaries/?team=CAR&date=01-01-2015 would return a game played on january 1st, 2015.

GET /game_summaries/ - return a specific game summary. Would more or less support this page: http://war-on-ice.com/game1.html?seasongcode=2014201530416

thoughts?

amandrycky commented 9 years ago

Would it make more sense to split by entity?

Example -- On that front page, you're looking at some distinct sets of data:

Would all of that come out in the same call (if we just had one from game_summaries)?

Or would it make sense to do something like

GET /goalie/?game=201420001 GET /skater/?game=201420001

Then those could be recycled for the other apps. Just a thought. I'll divert to the experts.

pacefalm commented 9 years ago

The only issue with that is that you'll end up making tons of small api calls when that page loads. Not necessarily a bad thing, it just depends on how we want to do it.