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
Copy file name to clipboardExpand all lines: documentation/API-design-guidelines.md
+19-12Lines changed: 19 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -905,6 +905,12 @@ Filtering consists of restricting the number of resources queried by specifying
905
905
Next, it is specified how it should be used according to the filtering based on the type of data being searched for: a number or a date and the type of operation.
906
906
907
907
Note: Services may not support all attributes for filtering. In case a query includes an attribute for which filtering is not supported, it may be ignored by the service.
908
+
909
+
#### Security Considerations
910
+
As filtering may reveal sensitive information, privacy and security constraints have to be considered when defining query parameters, e.g. it should not be possible to filter using personal information (such as name, phone number or IP address).
@@ -917,28 +923,29 @@ Note: Services may not support all attributes for filtering. In case a query in
917
923
918
924
And according to the filtering based on string and enums data, being searched for:
919
925
920
-
| **Operation** | **Strings/enums** |
921
-
|---------------|-----------------------|
922
-
| equal | `GET .../?name=Juan` |
923
-
| non equal | `GET .../?name!=Jonh` |
924
-
| Contains | `GET .../?name=~Rafa` |
925
926
927
+
| **Operation** | **Strings/enums** |
928
+
| ----- | ----- |
929
+
| equal | `GET .../?type=mobile` |
930
+
| non equal | `GET .../?type!=mobile` |
931
+
| Contains | `GET .../?type=~str` |
926
932
927
933
**Additional rules**:
928
934
- The operator "`&`" is evaluated as an AND between different attributes.
929
935
- A Query Param (attribute) can contain one or n values separated by "`,`".
930
936
- For operations on numeric, date or enumerated fields, the parameters with the suffixes `.(gte|gt|lte|lt)$` need to be defined, which should be used as comparators for “greater—equal to, greater than, smaller—equal to, smaller than” respectively. Only the parameters needed for given field should be defined e.g., with `.gte` and `.lte` suffixes only.
931
937
938
+
932
939
**Examples**:
933
-
- <u>Equals</u>: to search users with the first name "david" and last name "munoz":
934
-
- `GET /users?name=david&surname=munoz`
935
-
- `GET /users?name=David,Noelia`
940
+
- <u>Equals</u>: to search devices with a particular operating system and version or type:
941
+
- `GET /device?os=ios&version=17.0.1`
942
+
- `GET /device?type=apple,android`
936
943
- Search for several values separating them by "`,`".
937
944
- <u>Inclusion</u>: if we already have a filter that searches for "equal" and we want to provide it with the possibility of searching for "inclusion", we must include the character "~"
938
-
- `GET /users?name=dav`
939
-
- Search for the exact name "dav"
940
-
- `GET /users?name=~dav`
941
-
- Look for names that include "dav"
945
+
- `GET /device?version=17.0.1`
946
+
- Search for the exact version "17.0.1"
947
+
- `GET /device?version=~17.0`
948
+
- Look for version strings that include "17.0"
942
949
- <u>Greater than / less than</u>: new attributes need to be created with the suffixes `.(gte|gt|lte|lt)$` and included in `get` operation :
0 commit comments