TruckMuncher/TruckMuncher-Protos — pull request #1 by MariusVolkhart (2014-10-03 20:26:09+00:00)
Title: Phase1 API

Let the games... begin!

@atscott @jault3 @moorea @maconsuckow @nockertsb
This is an API implementation I came up with. This is pretty different from what we talked about on Thursday in SDL, so lets hear what you think!

## Regions
This API introduces the concept of a __Region__. A region is a geographic area that we define to contain a group of food trucks. We might define the Greater Milwaukee Region, Downtown Chicago, or all of New York as regions. The idea is that trucks within a region are highly mobile and it makes sense to cache a lot of their information that doesn't change.

Clients will not be aware of regions. Regions are a meta-concept on the API. Clients simply indicate their location.

## Data Separation
This API aims to separate the information that changes frequently from that which generally stays the same. This encourages caching and less data usage. But aren't Protobufs _already_ really small? Well, yes but this separation encourages several good performance patterns.

### How does it work
Look at the `getActiveTrucks` and `getTruckProfiles` routes. `getTruckProfiles` is used to fetch the data that probably doesn't change often: name, id, imageUrl. This only needs to be called when the app first loads, the user enters a new region, or when there is new data. This can be done through a push notification or through a background sync at night while plugged in and on wifi. `getActiveTrucks` is used to figure out where trucks are and whether or not they are serving. This call happens every time the app is opened.

#### But, but, but Web?!
Caching capabilities on the Web are a mystery to me. So how would this work then? Well, one option is for the Web platform to call both `getActiveTrucks` and `getTruckProfiles` in tandem to get all the information. The other option is to offer the ability to combine all the info into a single call. The `getFullMenus` route behaves this way. The `FullMenusRequest` allows the developer to specify where or not the availability should be included. In this case, the Web platform would always call `getFullMenus` and include the availability, and never make a call to `getMenuAvailabilityDiff`.

## Model Generation
It's worth noting that these protos are not intended or designed to be used as business objects. They are designed to enforce a strict API contract, and to deliver maximum value at their time of calling. Building internal business objects and such is left to the developer.

## Empty Requests and Responses?
Some of the RPCs require or return objects that are empty. This is to ensure backwards compatibility if in the future a field is added.

## These are not the verbs you're looking for...
Nope. No HTTP verbs to be found here. Everything is a POST since we require a body. All responses are a 200 unless there was an actual error, because all calls have a response object. The API also does not differentiate between an update and a create for objects like Categories.

# // TODO
- [ ] Determine feasibility of doing diffs. The Menu API was designed in a diff-style, while the Trucks API was done in a full-replacement style.
- [ ] Determine which method of fetching _all_ the data is better for the Web platform. Which is better for the backend platform?
- [ ] Squash the commits