In the previous articles on the StreetCart project:
- @Steve Traut introduced StreetCarts, an end-to-end API project that the Apigee docs team is building.
- @wwitman described the up-front planning and design issues we’ve been thinking and asking about.
In this article, I will describe the APIs that we plan to implement. These are the APIs that app developers use to create the different StreetCart apps. To implement these APIs, we will create API proxies on Edge,and then group them into API products.
Identifying the apps
Before we identified the APIs, we first identified the client apps. We plan on building three client apps:
- Me****mber app: Lets customers view truck information, view menus, write/read reviews, place orders, etc.
- Vendor app: Lets cart owners manage truck information, such as menus, menu items, and prices.
- Adm****in app: Lets back-office admins add new food carts, manage users, and perform other administrative tasks.
Grouping APIs by product
Each client app uses APIs from different API products. For example, the Admin app uses all of the available APIs, while the Member app does not use any of the Vendor or Admin APIs.
To group APIs by product, we defined four API products:
- Pub (P**):** Open APIs that can be called without any user authentication. For example, to view a food cart menu.
- Member (M): APIs that require log in with the “member” role. Let members create reviews, place orders, and edit orders.
- Vendor (V): APIs that require log in with the “vendor” role. Let vendors add/update/delete menus, menu items, and cart information.
- **Admin (**A): APIs that require log in with the “admin” role. Let admins perform any operation.
Defining the APIs
The following table lists the APIs that we plan for the first phase of the StreetCarts app. Notice that these APIs do not yet let the user purchase a food item. Those APIs are part of Phase 2.
For each API, the table lists:
- Use
- Supported HTTP verbs
- Inputs and return values
- API product containing the API
| API Path | Verb | Use | Input | Returns | P | M | V | A |
|---|---|---|---|---|---|---|---|---|
| /users query param: role |
GET | Get all users | Array of user IDs, first/last name, role | x | ||||
| POST | Add new user | User info object, including username/pw | User info object and user ID | x | ||||
| /users/{userID} | GET | Get user info | User ID | User info object | x | |||
| PUT | Update user info | User info object | User info object | x | ||||
| DEL | Delete user and all user info, such as reviews | User ID | x | |||||
| /token | POST | Get OAuth token to access protected APIs | User email/pw | OAuth token, including user role | x | |||
| /foodcarts query param: cuisine, city |
GET | Get all carts | Array of cart IDs, short descriptions | x | ||||
| POST | Add new cart | Cart info object | Cart info object with cart ID | x | ||||
| /foodcarts/{cartID} | GET | Get cart info | Cart ID | Cart info object with menu IDs. | x | |||
| PUT | Update cart info | Cart info object | Cart info object | x | ||||
| DEL | Delete cart and all cart info, such as menus, menu items. | Cart ID | x | |||||
| /foodcarts/{cartID}/menuItems | GET | Get all cart menu items | Cart ID | Array of all menu item IDs, names, and short descriptions | x | |||
| /foodcarts/{cartID}/menus | GET | Get all menus for a cart | Cart ID | Array of menu IDs, names, short descriptions | x | |||
| POST | Add empty menu | Cart ID, menu info object | Menu info object with menu ID | x | ||||
| /menus query param: menutype, cuisine |
Get | Get all menus for all carts menuType=breakfast, lunch, dinner, late night cuisine=Italian, Mexican, Indian, etc. |
Array of cart IDs, cart names, menu IDs, short menu descriptions | x | ||||
| /menus/{menuID} | GET | Get menu items, menu info | Cart/Menu ID | Menu info object, Array of menu items | x | |||
| PUT | Update menu info | Cart ID, menu info object | Menu info object | x | ||||
| DEL | Del menu | x | ||||||
| /menus/{menuID}/menuItems | GET | Get menu items | Cart/menu ID | Array of all menu item IDs, names, and short descriptions | x | |||
| menus/{menuID}/menuItems/{itemID} | POST | Add menu item to menu | Cart/Menu/Item ID | Menu object | x | |||
| DEL | Del menu item from menu | Cart/Menu/Item ID | x | |||||
| **/**menuItems query param: cuisine, truck ID |
GET | Get all menu items cuisine=Italian, Mexican, Indian, etc. |
Array of all menu item IDs, cart IDs, item names, short descriptions | x | ||||
| POST | Create new menu item | Object describing menu item, including cartID | Menu item info object with item ID | x | ||||
| /menuItems/{itemID} | GET | Get menu item | Menu item ID | Menu item info object | x | |||
| PUT | Update menu item | Menu item ID, item info | Menu item info object | x | ||||
| DEL | Delete menu item, and delete it from all menus | Menu item ID | x | |||||
| /reviews query param: cartID, userID |
GET | Get all reviews for all carts | Array of review IDs, cart IDs, cart name, review object | x | ||||
| /reviews/{reviewID} | Get | Get a specific review | x | |||||
| /reviews/users/{userID} | GET | Get all reviews for a user | Cart ID | Array of review IDs, review object | x | |||
| POST | Add a review | Cart ID, user ID, review object | Review object with ID | x | ||||
| PUT | Update review | Cart ID, user ID, review object | Review object | x | ||||
| DEL | Delete review | Review ID | x |