Pragmatically RESTful
This API is designed to pragmatically conform to RESTful principles. We use the word pragmatically as this API is not uniformly RESTful. For example, including an API version number in a resource URI is contrary to REST. Yet, we have decided to version API. This allows us to grow the API as needed (even if it changes core functionality) and maintain legacy code for existing applications.
CRUD (Create, Read, Update, Delete)
In accordance with RESTful constraints, every resource has a consistent URI and may have one of 4 actions applied to it (Create, Read, Update, Delete) by accessing the URI via one of 4 HTTP methods (POST, GET, PUT, DELETE respectively). However, because most browsers do not support PUT and DELETE via HTML forms, we allow emulation of these methods via the POST method by including a parameter _method=put or _method=delete.
Generally, collections are accessed with a URI like https://api.weathersource.com/v1/collection. Elements are accessed with a URI likehttps://api.weathersource.com/v1/collection/:id.
| Create (POST) | Read (GET) | Update (PUT) | Delete (DELETE) | |
|---|---|---|---|---|
| Collection | Create new element POST /collection |
Show collection GET /collection |
Bulk update collection PUT /collection POST /collection?_method=put |
Delete collection DELETE /collection POST /collection?_method=delete |
| Element | Error | Show element POST /collection/:id |
Update element PUT /collection/:id POST /collection/:id?_method=put |
Delete element DELETE /collection/:id POST /collection/:id?_method=delete |
