@@ -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
7546Add 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