Skip to content

Commit 1ecb026

Browse files
committed
docs: Move Motivation down in README
1 parent cec5200 commit 1ecb026

File tree

1 file changed

+29
-29
lines changed

1 file changed

+29
-29
lines changed

README.md

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -41,35 +41,6 @@ which encodes most non-alphanumeric characters.
4141
- Serialization of functions or other objects is not supported
4242
and will throw an `UnserializableParamError`.
4343

44-
## Motivation
45-
46-
URL search parameters are strings, however the Seam API will parse parameters as complex types.
47-
The Seam SDK must accept the complex types as input and serialize these
48-
to search parameters in a way supported by the Seam API.
49-
50-
There is no single standard for this serialization.
51-
This module establishes the serialization standard adopted by the Seam API.
52-
53-
### Why not use [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)?
54-
55-
- Passing a raw object to URLSearchParams has unpredictable serialization behavior.
56-
57-
### Why not [qs](https://github.com/ljharb/qs)?
58-
59-
- Not a zero-dependency module. Has quite a few dependency layers.
60-
- Impractical as a reference implementation.
61-
qs enables complex, non-standard parsing and serialization,
62-
which makes ensuing SDK parity much harder.
63-
Similarly, this puts an unreasonable burden on user's of the HTTP API or those implementing their own client.
64-
- The Seam API must ensure it handles a well defined set of non-string query parameters consistency.
65-
Using qs would allow the SDK to send unsupported or incorrectly serialized parameter types to the API
66-
resulting in unexpected behavior.
67-
68-
### Why not use the default [Axios](https://axios-http.com/) serializer?
69-
70-
- Using the default [Axios] serializer was the original approach,
71-
however it had similar issues to using URLSearchParams and qs as noted above.
72-
7344
## Installation
7445

7546
Add this as a dependency to your project using [npm] with
@@ -137,6 +108,35 @@ const { data } = await client.get('/search', {
137108

138109
[Axios]: https://axios-http.com/
139110

111+
## Motivation
112+
113+
URL search parameters are strings, however the Seam API will parse parameters as complex types.
114+
The Seam SDK must accept the complex types as input and serialize these
115+
to search parameters in a way supported by the Seam API.
116+
117+
There is no single standard for this serialization.
118+
This module establishes the serialization standard adopted by the Seam API.
119+
120+
### Why not use [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)?
121+
122+
- Passing a raw object to URLSearchParams has unpredictable serialization behavior.
123+
124+
### Why not [qs](https://github.com/ljharb/qs)?
125+
126+
- Not a zero-dependency module. Has quite a few dependency layers.
127+
- Impractical as a reference implementation.
128+
qs enables complex, non-standard parsing and serialization,
129+
which makes ensuing SDK parity much harder.
130+
Similarly, this puts an unreasonable burden on user's of the HTTP API or those implementing their own client.
131+
- The Seam API must ensure it handles a well defined set of non-string query parameters consistency.
132+
Using qs would allow the SDK to send unsupported or incorrectly serialized parameter types to the API
133+
resulting in unexpected behavior.
134+
135+
### Why not use the default [Axios](https://axios-http.com/) serializer?
136+
137+
- Using the default [Axios] serializer was the original approach,
138+
however it had similar issues to using URLSearchParams and qs as noted above.
139+
140140
## Development and Testing
141141

142142
### Quickstart

0 commit comments

Comments
 (0)