You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
REST Layer is an API framework heavily inspired by the excellent [Python Eve](http://python-eve.org). It helps you create a comprehensive, customizable, and secure REST (graph) API on top of pluggable [backend storages](#storage-handlers) with no boiler plate code so you can focus on your business logic.
8
8
@@ -40,7 +40,17 @@ The REST Layer framework is composed of several sub-packages:
40
40
-[Hooks](#hooks)
41
41
-[Sub Resources](#sub-resources)
42
42
-[Dependency](#dependency)
43
-
-[Quering](#quering)
43
+
-[HTTP Request Headers](#http-request-headers)
44
+
-[Prefer](#prefer)
45
+
-[HTTP Request Methods](#http-request-methods)
46
+
-[OPTIONS](#options)
47
+
-[HEAD](#head)
48
+
-[GET](#get)
49
+
-[POST](#post)
50
+
-[PUT](#put)
51
+
-[PATCH](#patch)
52
+
-[DELETE](#delete)
53
+
-[Querying](#querying)
44
54
-[Filtering](#filtering)
45
55
-[Sorting](#sorting)
46
56
-[Field Selection](#field-selection)
@@ -52,16 +62,6 @@ The REST Layer framework is composed of several sub-packages:
-[Extensible Data Validation](#extensible-data-validation)
@@ -77,22 +77,26 @@ The REST Layer framework is composed of several sub-packages:
77
77
78
78
## Breaking Changes
79
79
80
-
Until version 1.0 of rest-layer, breaking changes may occur at any time if you rely on the latest master version.
80
+
Until we reach a stable v1, there will be occasional breaking changes to the rest-layer APIs. Breaking changes will however not arrive at patch releases.
81
81
82
-
Below is an overview over recent breaking changes, starting from an arbitrary point with PR #151:
82
+
## Breaking changes since v0.2.0
83
+
84
+
No breaking changes since v0.2.0.
85
+
86
+
## Breaking changes prior to v0.2.0
87
+
88
+
Below is an incomplete list of breaking changes included in v0.2.0:
83
89
84
90
- PR #151: `ValuesValidator FieldValidator` attribute in `schema.Dict` struct replaced by `Values Field`.
85
91
- PR #179: `ValuesValidator FieldValidator` attribute in `schema.Array` struct replaced by `Values Field`.
86
-
- PR #204:
92
+
- PR #204:
87
93
- Storage drivers need to accept pointer to `Expression` implementer in `query.Predicate`.
88
94
-`filter` parameters in sub-query will be validated for type match.
89
95
-`filter` parameters will be validated for type match only, instead of type & constrains.
90
96
- PR #228: `Reference` projection fields will be validated against referenced resource schema.
91
97
- PR #230: `Connection` projection fields will be validated against connected resource schema.
92
98
- PR #241: Always call `OnUpdate` field hook on HTTP PUT for existing documents. Deleting a field with `Default` value set, will always be reset to its default value.
93
99
94
-
From the next release and onwards (0.2), this list will summarize breaking changes done to master since the last release.
95
-
96
100
## Features
97
101
98
102
-[x] Automatic handling of REST resource operations
@@ -145,16 +149,17 @@ As REST Layer is a simple `net/http` handler. You can use standard middleware to
-[return=minimal](https://tools.ietf.org/html/rfc7240#section-4.2): When a request is successfully (HTTP Response Status of `200` or `201`), response body is not returned. For Response Status of `200 OK`, status becomes `204 No Content`. Can be used for e.g `PUT`, `POST` and `PATCH` methods, where returned body will be known by the client.
853
+
-[return=no-content](https://msdn.microsoft.com/en-us/library/hh537533.aspx): same as `return=minimal`.
The Content-Type of the request body. Most HTTP methods only support `"aplication/json"` by default, but `PUT` requests also allow `"application/json-patch+json"`.
865
+
866
+
## HTTP Request Methods
867
+
868
+
Following HTTP Methods are currently supported by rest-layer.
869
+
870
+
### OPTIONS
871
+
872
+
Used to tell the client which HTTP Methods are supported for any given path.
873
+
874
+
### HEAD
875
+
876
+
The same as `GET`, except it includes only headers in the response.
877
+
878
+
### GET
879
+
880
+
Used to retrieve a (projected[#field-selection]) resource document by specifying it's `ID` in the path, or to retrieve a paginated view of documents matching a [query](#quering).
881
+
882
+
### POST
883
+
884
+
Used to create new resource document when the `ID` can be generated by the server. Field default values are set for omitted fields, and `OnCreate` field hooks are issued.
885
+
886
+
### PUT
887
+
888
+
Used to create or update a single resource document by specifying it's `ID` in the path. Field default values are set for omitted fields. If the document did not previously exist `OnCreate` field hooks are issued, otherwise `OnUpdate` field hooks are issued.
889
+
890
+
`If-Match`[concurrency protection](#data-integrity-and-concurrency-control) could be used if relevant.
891
+
892
+
### PATCH
893
+
894
+
Used to create or patch a single resource document by specifying it's `ID` in the path. `OnUpdate` field hooks are issued.
895
+
896
+
REST Layer supports two PATCH protocols, that can be specified via the `Content-Type` header.
897
+
898
+
- Simple filed replacement [RFC-5789](http://tools.ietf.org/html/rfc5789) - this protocol will update only supplied top level fields, and will leave other fields in the document intact. This means that this protocol can't delete fields. Using this protocol is specified with `Content-Type: application/json` HTTP Request header.
899
+
900
+
-[JSON-Patch/RFC-6902](https://tools.ietf.org/html/rfc6902) - When patching deeply nested documents, it is more convenient to use protocol designed especially for this. Using this protocol is specified with `Content-Type: application/json-patch+json` HTTP Request header.
901
+
902
+
`If-Match`[concurrency protection](#data-integrity-and-concurrency-control) could be used if relevant.
903
+
904
+
Example JSON Patch Request where we utilize concurrency control ask for the response body to be omitted:
Used to delete single resource document given its `ID`, or multiple documents matching a [query](#quering).
916
+
917
+
## Querying
842
918
843
919
When supplying query parameters be sure to honor URL encoding scheme. If you need to include `+` sign, use `%2B`, etc.
844
920
@@ -904,7 +980,7 @@ The flags are:
904
980
|`i` |case-insensitive | false
905
981
|`m` |multi-line mode: ^ and $ match begin/end line in addition to begin/end text| false
906
982
|`s` |let . match \n | false
907
-
|`U` |ungreedy: swap meaning of x\* and x\*?, x+ and x+?, etc | false
983
+
|`U` |non-greedy: swap meaning of x\* and x\*?, x+ and x+?, etc | false
908
984
909
985
For example the following regular expression would match any document with a field `type` and its value `rest-layer`.
910
986
@@ -919,7 +995,7 @@ The same example with flags:
919
995
```
920
996
921
997
However, keep in mind that Storers have to support regular expression and depending on the implementation of the storage handler the accepted syntax may vary.
922
-
An error of `ErrNotImplemented` will be returned for those storage backends which do not support the `$regex` operator.
998
+
An error of `ErrNotImplemented` will be returned for those storage back-ends which do not support the `$regex` operator.
923
999
924
1000
The `$elemMatch` operator matches documents that contain an array field with at least one element that matches all the specified query criteria.
925
1001
```go
@@ -934,14 +1010,18 @@ The `$elemMatch` operator matches documents that contain an array field with at
934
1010
```
935
1011
936
1012
Matching documents that contain specific values within array objects can be done with `$elemMatch`:
The snippet above will return all documents, which `telephones` array field contains objects that have `name` **_AND_** `active` fields matching queried values.
941
1019
> Note that documents returned may contain other objects in `telephones` that don't match the query above, but at least one object will do. Further filtering could be needed on the API client side.
942
1020
943
1021
#### *$elemMatch* Limitation
1022
+
944
1023
`$elemMatch` will work only for arrays of objects for now. Later it could be extended to work on plain arrays e.g:
1024
+
945
1025
```js
946
1026
{numbers: {$elemMatch: {$gt:20}}}
947
1027
```
@@ -970,13 +1050,13 @@ Sorting of resource items is defined through the `sort` query-string parameter.
970
1050
971
1051
To use a resource field with the `sort` parameter, the field must be defined on the resource and the `Sortable` field property must be set to `true`. You may want to ensure the backend database has this field indexed when enabled.
972
1052
973
-
Here we sort the result by ascending quantity and descending date:
1053
+
Here we sort the result by ascending quantity and descending create time:
974
1054
975
1055
/posts?sort=quantity,-created
976
1056
977
1057
### Field Selection
978
1058
979
-
REST APIs tend to grow over time. Resources get more and more fields to fulfill the needs for new features. But each time fields are added, all existing API clients automatically get the additional cost. This tend to lead to huge waste of bandwidth and added latency due to the transfer of unnecessary data. As a workaround, the `field` parameter can be used to minimize and customize the response body from requests with a `GET`, `PATCH`or `PUT` method on resource URLs.
1059
+
REST APIs tend to grow over time. Resources get more and more fields to fulfill the needs for new features. But each time fields are added, all existing API clients automatically get the additional cost. This tend to lead to huge waste of bandwidth and added latency due to the transfer of unnecessary data. As a workaround, the `field` parameter can be used to minimize and customize the response body from requests with a `GET`, `POST`, `PUT`or `PATCH` method on resource URLs.
980
1060
981
1061
REST Layer provides a powerful fields selection (also named projection) system. If you provide the `fields` parameter with a list of fields for the resource you are interested in separated by commas, only those fields will be returned in the document:
@@ -1224,61 +1305,6 @@ This time the update operation was accepted and we got a new `ETag` for the upda
1224
1305
1225
1306
Concurrency control header `If-Match` can be used with all mutation methods on item URLs: `PATCH` (update), `PUT` (replace) and `DELETE` (delete).
1226
1307
1227
-
## HTTP Headers Support
1228
-
1229
-
### Prefer
1230
-
1231
-
Currently supported values are:
1232
-
- [return=minimal](https://tools.ietf.org/html/rfc7240#section-4.2) - When request is successfull (HTTP Response Status of `200` or `201`), response body is not returned. For Response Status of `200OK`, status becomes `204 No Content`. Usefull for `PUT`, `POST` and `PATCH` methods, where returned body will be known by the client.
1233
-
- [return-no-content](https://msdn.microsoft.com/en-us/library/hh537533.aspx) - same as `return=minimal`.
The same as [GET](#get), except that it doesn't return any body.
1248
-
1249
-
### GET
1250
-
Used to query a resource with its sub/embedded resources.
1251
-
1252
-
### POST
1253
-
Used to create new resource document, where new `ID` is generated from the server.
1254
-
1255
-
### PUT
1256
-
Used to create/update single resource document given its `ID`. On initial request, `onInsert` resource hook will be called. All subsequent `PUT` requests will call `onUpdate` resource hook.
1257
-
1258
-
Be aware when dealing with resource fields with `Default` set. If missing from payload or deleted, such fields will be reset to their `default value`.
1259
-
1260
-
### PATCH
1261
-
Used to update/patch single resource document given its `ID`. REST Layer supports following update protocols:
1262
-
1263
-
- Simple filed replacement [RFC-5789](http://tools.ietf.org/html/rfc5789) - this protocol will update only supplied top level fields, and will leave other fields in the document intact. This means that this protocol can't delete fields. Using this protocol is specified with `Content-Type: application/json` HTTP Request header.
1264
-
1265
-
- [JSON-Patch/RFC-6902](https://tools.ietf.org/html/rfc6902) - When patching deeply nested documents, it is more convenient to use protocol designed especially for this. Using this protocol is specified with `Content-Type: application/json-patch+json` HTTP Request header.
1266
-
1267
-
If using `If-Match` concurrency control as described in the [data control and integrity section](#data-integrity-and-concurrency-control), you could potentially choose to calculate the body of new object client side. Note that the response body for a successful operation can be omitted by supplying a HTTP request header: `Prefer:return=minimal`.
Used to delete single resource document given its `ID`, or via [Query](#quering).
1278
-
1279
-
### OPTIONS
1280
-
Used to tell the client, which HTTP Methods are supported on a given resource.
1281
-
1282
1308
## Data Validation
1283
1309
1284
1310
Data validation is provided out-of-the-box. Your configuration includes a schema definition for every resource managed by the API. Data sent to the API to be inserted/updated will be validated against the schema, and a resource will only be updated if validation passes. See [Field Definition](#field-definition) section to know more about how to configure your validators.
0 commit comments