@typespec/http 0.47.0-dev.2 → 0.47.0-dev.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +410 -68
  2. package/lib/http-decorators.tsp +12 -12
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,106 +1,448 @@
1
- # TypeSpec HTTP Library
1
+ # @typespec/http
2
2
 
3
- This package provides [TypeSpec](https://github.com/microsoft/TypeSpec) decorators, models, and interfaces to describe HTTP APIs. With fundamental models and decorators defined in TypeSpec.Http namespace, you will be able describe basic http level operations.
3
+ TypeSpec HTTP protocol binding
4
4
 
5
5
  ## Install
6
6
 
7
- In your typespec project root
8
-
9
7
  ```bash
10
8
  npm install @typespec/http
11
9
  ```
12
10
 
13
- ## Usage
11
+ ## Decorators
12
+
13
+ ### TypeSpec.Http
14
14
 
15
- ```TypeSpec
16
- import "@typespec/http";
15
+ - [`@body`](#@body)
16
+ - [`@delete`](#@delete)
17
+ - [`@get`](#@get)
18
+ - [`@head`](#@head)
19
+ - [`@header`](#@header)
20
+ - [`@includeInapplicableMetadataInPayload`](#@includeinapplicablemetadatainpayload)
21
+ - [`@patch`](#@patch)
22
+ - [`@path`](#@path)
23
+ - [`@post`](#@post)
24
+ - [`@put`](#@put)
25
+ - [`@query`](#@query)
26
+ - [`@route`](#@route)
27
+ - [`@server`](#@server)
28
+ - [`@sharedRoute`](#@sharedroute)
29
+ - [`@statusCode`](#@statuscode)
30
+ - [`@useAuth`](#@useauth)
17
31
 
18
- using TypeSpec.Http;
32
+ #### `@body`
33
+
34
+ Explicitly specify that this property is to be set as the body
35
+
36
+ ```typespec
37
+ @TypeSpec.Http.body
19
38
  ```
20
39
 
21
- For more information, consult the [HTTP](https://microsoft.github.io/typespec/docs/standard-library/http/) section of the TypeSpec guide.
40
+ ##### Target
22
41
 
23
- ## Library Tour
42
+ `ModelProperty`
24
43
 
25
- `@typespec/http` library defines of the following artifacts:
44
+ ##### Parameters
26
45
 
27
- - [TypeSpec HTTP Library](#typespec-http-library)
28
- - [Install](#install)
29
- - [Usage](#usage)
30
- - [Library Tour](#library-tour)
31
- - [Models](#models)
32
- - [Decorators](#decorators)
33
- - [See also](#see-also)
46
+ None
34
47
 
35
- ## Models
48
+ ##### Examples
36
49
 
37
- | Model | Notes |
38
- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
39
- | LocationHeader | Location header |
40
- | Response<Status> | <Status> is numerical status code. |
41
- | OkResponse<T> | Response<200> with T as the response body model type. |
42
- | CreatedResponse | Response<201> |
43
- | AcceptedResponse | Response<202> |
44
- | NoContentResponse | Response<204> |
45
- | MovedResponse | Response<301> with LocationHeader for redirected URL |
46
- | NotModifiedResponse | Response<304> |
47
- | UnauthorizedResponse | Response<401> |
48
- | NotFoundResponse | Response<404> |
49
- | ConflictResponse | Response<409> |
50
- | PlainData<T> | Produces a new model with the same properties as T, but with @query, @header, @body, and @path decorators removed from all properties. |
51
- | BasicAuth | Configure `basic` authentication with @useAuth |
52
- | BearerAuth | Configure `bearer` authentication with @useAuth |
53
- | ApiKeyAuth<TLocation, TName> | Configure `apiKey` authentication with @useAuth |
54
- | OAuth2Auth<TFlows> | Configure `oauth2` authentication with @useAuth |
50
+ ```typespec
51
+ op upload(@body image: bytes): void;
52
+ op download(): {
53
+ @body image: bytes;
54
+ };
55
+ ```
55
56
 
56
- ## Decorators
57
+ #### `@delete`
58
+
59
+ Specify the HTTP verb for the target operation to be `DELETE`.
60
+
61
+ ```typespec
62
+ @TypeSpec.Http.delete
63
+ ```
64
+
65
+ ##### Target
66
+
67
+ `Operation`
68
+
69
+ ##### Parameters
70
+
71
+ None
72
+
73
+ ##### Examples
74
+
75
+ ```typespec
76
+ @delete op set(petId: string): void;
77
+ ```
78
+
79
+ #### `@get`
80
+
81
+ Specify the HTTP verb for the target operation to be `GET`.
82
+
83
+ ```typespec
84
+ @TypeSpec.Http.get
85
+ ```
86
+
87
+ ##### Target
88
+
89
+ `Operation`
90
+
91
+ ##### Parameters
92
+
93
+ None
94
+
95
+ ##### Examples
96
+
97
+ ```typespec
98
+ @get op read(): string;
99
+ ```
100
+
101
+ #### `@head`
102
+
103
+ Specify the HTTP verb for the target operation to be `HEAD`.
104
+
105
+ ```typespec
106
+ @TypeSpec.Http.head
107
+ ```
108
+
109
+ ##### Target
110
+
111
+ `Operation`
112
+
113
+ ##### Parameters
114
+
115
+ None
116
+
117
+ ##### Examples
118
+
119
+ ```typespec
120
+ @head op ping(petId: string): void;
121
+ ```
57
122
 
58
- The `@typespec/http` library defines the following decorators in `TypeSpec.Http` namespace:
123
+ #### `@header`
59
124
 
60
- | Declarator | Scope | Usage |
61
- | ----------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
- | @get | operations | indicating operation uses HTTP `GET` verb. |
63
- | @put | operations | indicating operation uses HTTP `PUT` verb. |
64
- | @post | operations | indicating operation uses HTTP `POST` verb. |
65
- | @patch | operations | indicating operation uses HTTP `PATCH` verb. |
66
- | @delete | operations | indicating operation uses HTTP `DEL` verb. |
67
- | @head | operations | indicating operation uses HTTP `HEAD` verb. |
68
- | @header | model properties and operation parameters | indicating the properties are request or response headers. |
69
- | @query | model properties and operation parameters | indicating the properties are in the request query string. |
70
- | @body | model properties and operation parameters | indicating the property is in request or response body. Only one allowed per model and operation. |
71
- | @path | model properties and operation parameters | indicating the properties are in request path. |
72
- | @statusCode | model properties and operation parameters | indicating the property is the return status code. Only one allowed per model. |
73
- | @server | namespace | Configure the server url for the service. |
74
- | @route | operations, namespaces, interfaces | Syntax:<br> `@route(routeString)`<br><br>Note:<br>`@route` defines the relative route URI for the target operation. The `routeString` argument should be a URI fragment that may contain one or more path parameter fields. If the namespace or interface that contains the operation is also marked with a `@route` decorator, it will be used as a prefix to the route URI of the operation. |
75
- | @useAuth | namespace | Configure the service authentication. |
125
+ Specify this property is to be sent or received as an HTTP header.
76
126
 
77
- ## How to
127
+ ```typespec
128
+ @TypeSpec.Http.header(headerNameOrOptions?: string | TypeSpec.Http.HeaderOptions)
129
+ ```
130
+
131
+ ##### Target
78
132
 
79
- ### Specify content type
133
+ `ModelProperty`
80
134
 
81
- To specify the content type you can add a `@header contentType: <value>` in the operation parameter(For request content type) or return type(For response content type)
135
+ ##### Parameters
82
136
 
83
- Example: return `application/png` byte body
137
+ | Name | Type | Description |
138
+ | ------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139
+ | headerNameOrOptions | `union string \| TypeSpec.Http.HeaderOptions` | Optional name of the header when sent over HTTP or header options.<br />By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`) |
140
+
141
+ ##### Examples
84
142
 
85
143
  ```typespec
86
- op getPng(): {
87
- @header contentType: "application/png";
88
- @body _: bytes;
144
+ op read(@header accept: string): {
145
+ @header("ETag") eTag: string;
89
146
  };
147
+ op create(
148
+ @header({
149
+ name: "X-Color",
150
+ format: "csv",
151
+ })
152
+ colors: string[],
153
+ ): void;
154
+ ```
155
+
156
+ ###### Implicit header name
157
+
158
+ ```typespec
159
+ op read(): {
160
+ @header contentType: string;
161
+ }; // headerName: content-type
162
+ op update(@header ifMatch: string): void; // headerName: if-match
163
+ ```
164
+
165
+ #### `@includeInapplicableMetadataInPayload`
166
+
167
+ Specify if inapplicable metadata should be included in the payload for the given entity.
168
+
169
+ ```typespec
170
+ @TypeSpec.Http.includeInapplicableMetadataInPayload(value: valueof boolean)
171
+ ```
172
+
173
+ ##### Target
174
+
175
+ `(intrinsic) unknown`
176
+
177
+ ##### Parameters
178
+
179
+ | Name | Type | Description |
180
+ | ----- | ------------------------ | --------------------------------------------------------------- |
181
+ | value | `valueof scalar boolean` | If true, inapplicable metadata will be included in the payload. |
182
+
183
+ #### `@patch`
184
+
185
+ Specify the HTTP verb for the target operation to be `PATCH`.
186
+
187
+ ```typespec
188
+ @TypeSpec.Http.patch
189
+ ```
190
+
191
+ ##### Target
192
+
193
+ `Operation`
194
+
195
+ ##### Parameters
196
+
197
+ None
198
+
199
+ ##### Examples
200
+
201
+ ```typespec
202
+ @patch op update(pet: Pet): void;
203
+ ```
204
+
205
+ #### `@path`
206
+
207
+ Explicitly specify that this property is to be interpolated as a path parameter.
208
+
209
+ ```typespec
210
+ @TypeSpec.Http.path(paramName?: valueof string)
211
+ ```
212
+
213
+ ##### Target
214
+
215
+ `ModelProperty`
216
+
217
+ ##### Parameters
218
+
219
+ | Name | Type | Description |
220
+ | --------- | ----------------------- | --------------------------------------------------- |
221
+ | paramName | `valueof scalar string` | Optional name of the parameter in the url template. |
222
+
223
+ ##### Examples
224
+
225
+ ```typespec
226
+ @route("/read/{explicit}/things/{implicit}")
227
+ op read(@path explicit: string, implicit: string): void;
228
+ ```
229
+
230
+ #### `@post`
231
+
232
+ Specify the HTTP verb for the target operation to be `POST`.
233
+
234
+ ```typespec
235
+ @TypeSpec.Http.post
90
236
  ```
91
237
 
92
- Example: expect `application/png` byte body
238
+ ##### Target
239
+
240
+ `Operation`
241
+
242
+ ##### Parameters
243
+
244
+ None
245
+
246
+ ##### Examples
247
+
248
+ ```typespec
249
+ @post op create(pet: Pet): void;
250
+ ```
251
+
252
+ #### `@put`
253
+
254
+ Specify the HTTP verb for the target operation to be `PUT`.
255
+
256
+ ```typespec
257
+ @TypeSpec.Http.put
258
+ ```
259
+
260
+ ##### Target
261
+
262
+ `Operation`
263
+
264
+ ##### Parameters
265
+
266
+ None
267
+
268
+ ##### Examples
269
+
270
+ ```typespec
271
+ @put op set(pet: Pet): void;
272
+ ```
273
+
274
+ #### `@query`
275
+
276
+ Specify this property is to be sent as a query parameter.
277
+
278
+ ```typespec
279
+ @TypeSpec.Http.query(queryNameOrOptions?: string | TypeSpec.Http.QueryOptions)
280
+ ```
281
+
282
+ ##### Target
283
+
284
+ `ModelProperty`
285
+
286
+ ##### Parameters
287
+
288
+ | Name | Type | Description |
289
+ | ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------- |
290
+ | queryNameOrOptions | `union string \| TypeSpec.Http.QueryOptions` | Optional name of the query when included in the url or query parameter options. |
291
+
292
+ ##### Examples
293
+
294
+ ```typespec
295
+ op read(@query select: string, @query("order-by") orderBy: string): void;
296
+ op list(
297
+ @query({
298
+ name: "id",
299
+ format: "multi",
300
+ })
301
+ ids: string[],
302
+ ): void;
303
+ ```
304
+
305
+ #### `@route`
306
+
307
+ Defines the relative route URI for the target operation
308
+
309
+ The first argument should be a URI fragment that may contain one or more path parameter fields.
310
+ If the namespace or interface that contains the operation is also marked with a `@route` decorator,
311
+ it will be used as a prefix to the route URI of the operation.
312
+
313
+ `@route` can only be applied to operations, namespaces, and interfaces.
314
+
315
+ ```typespec
316
+ @TypeSpec.Http.route(path: valueof string, options?: (anonymous model))
317
+ ```
318
+
319
+ ##### Target
320
+
321
+ `union Namespace | Interface | Operation`
322
+
323
+ ##### Parameters
324
+
325
+ | Name | Type | Description |
326
+ | ------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
327
+ | path | `valueof scalar string` | Relative route path. Cannot include query parameters. |
328
+ | options | `model (anonymous model)` | Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. |
329
+
330
+ ##### Examples
331
+
332
+ ```typespec
333
+ @route("/widgets")
334
+ op getWidget(@path id: string): Widget;
335
+ ```
336
+
337
+ #### `@server`
338
+
339
+ Specify the endpoint for this service.
340
+
341
+ ```typespec
342
+ @TypeSpec.Http.server(url: valueof string, description: valueof string, parameters?: Record<unknown>)
343
+ ```
344
+
345
+ ##### Target
346
+
347
+ `Namespace`
348
+
349
+ ##### Parameters
350
+
351
+ | Name | Type | Description |
352
+ | ----------- | ----------------------- | ------------------------------------------------------- |
353
+ | url | `valueof scalar string` | Server endpoint |
354
+ | description | `valueof scalar string` | Description of the endpoint |
355
+ | parameters | `model Record<unknown>` | Optional set of parameters used to interpolate the url. |
356
+
357
+ ##### Examples
358
+
359
+ ```typespec
360
+ @service
361
+ @server("https://example.com", "Single server endpoint")
362
+ namespace PetStore;
363
+ ```
364
+
365
+ ###### parameterized
366
+
367
+ ```typespec
368
+ @server("https://{region}.foo.com", "Regional endpoint", {
369
+ @doc("Region name")
370
+ region?: string = "westus",
371
+ })
372
+ ```
373
+
374
+ #### `@sharedRoute`
375
+
376
+ `@sharedRoute` marks the operation as sharing a route path with other operations.
377
+
378
+ When an operation is marked with `@sharedRoute`, it enables other operations to share the same
379
+ route path as long as those operations are also marked with `@sharedRoute`.
380
+
381
+ `@sharedRoute` can only be applied directly to operations.
382
+
383
+ ```typespec
384
+ @sharedRoute
385
+ @route("/widgets")
386
+ op getWidget(@path id: string): Widget;
387
+ ```
93
388
 
94
389
  ```typespec
95
- op getPng(@header contentType: "application/png", @body _: bytes): void;
390
+ @TypeSpec.Http.sharedRoute
96
391
  ```
97
392
 
98
- ## See also
393
+ ##### Target
99
394
 
100
- - [HTTP example](https://cadlplayground.z22.web.core.windows.net/?c=aW1wb3J0ICJAY2FkbC1sYW5nL3Jlc3QiOwoKQHNlcnZpY2VUaXRsZSgiV2lkZ2V0IFPGFSIpCm5hbWVzcGFjZSBEZW1vxxg7CnVzaW5nIENhZGwuSHR0cDsKCm1vZGVsIMdAewogIEBrZXkgaWQ6IHN0cmluZzsKICB3ZWlnaHQ6IGludDMyxBFjb2xvcjogInJlZCIgfCAiYmx1ZSI7Cn0KCkBlcnJvcsdWRcQMxVVjb2Rly0BtZXNzYWdlymR9CgppbnRlcmbkALLmAI3nALTFP0DkAJ1saXN0KCk6xx9bXSB8xmHEUUByb3V0ZSgid8Uccy97aWR9IinGOHJlYWQoQHBhdGjrANfJSM1GcG9zdCBjcmVhdGUoQGJvZHkgxAXIK9Y0x3pjdXN0b21HZXTId8kR6gC0yjh9Cg%3D%3D):
101
- - [TypeSpec Getting Started](https://github.com/microsoft/typespec#getting-started)
102
- - [TypeSpec Website](https://microsoft.github.io/typespec)
395
+ `Operation`
103
396
 
397
+ ##### Parameters
398
+
399
+ None
400
+
401
+ #### `@statusCode`
402
+
403
+ Specify the status code for this response. Property type must be a status code integer or a union of status code integer.
404
+
405
+ ```typespec
406
+ @TypeSpec.Http.statusCode
407
+ ```
408
+
409
+ ##### Target
410
+
411
+ `ModelProperty`
412
+
413
+ ##### Parameters
414
+
415
+ None
416
+
417
+ ##### Examples
418
+
419
+ ```typespec
420
+ op read(): {@statusCode: 200, @body pet: Pet}
421
+ op create(): {@statusCode: 201 | 202}
422
+ ```
423
+
424
+ #### `@useAuth`
425
+
426
+ Specify this service authentication. See the [documentation in the Http library][https://microsoft.github.io/typespec/standard-library/rest/authentication] for full details.
427
+
428
+ ```typespec
429
+ @TypeSpec.Http.useAuth(auth: {} | Union | {}[])
104
430
  ```
105
431
 
432
+ ##### Target
433
+
434
+ `Namespace`
435
+
436
+ ##### Parameters
437
+
438
+ | Name | Type | Description |
439
+ | ---- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
440
+ | auth | `union {} \| Union \| {}[]` | Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple(Must use all authentication together) |
441
+
442
+ ##### Examples
443
+
444
+ ```typespec
445
+ @service
446
+ @useAuth(BasicAuth)
447
+ namespace PetStore;
106
448
  ```
package/lib/http-decorators.tsp CHANGED
@@ -7,7 +7,7 @@ using TypeSpec.Reflection;
7
7
  */
8
8
  model HeaderOptions {
9
9
  /**
10
- * Name of the header when sent over http.
10
+ * Name of the header when sent over HTTP.
11
11
  */
12
12
  name?: string;
13
13
 
@@ -18,23 +18,23 @@ model HeaderOptions {
18
18
  }
19
19
 
20
20
  /**
21
- * Specify this property is to be sent or received as an http header.
21
+ * Specify this property is to be sent or received as an HTTP header.
22
22
  *
23
- * @param headerNameOrOptions Optional name of the header when sent over http or header options.
24
- * By default the header name will be the property name converted from camelCase to camel-case. (e.g. `eTag` -> `e-tag`)
23
+ * @param headerNameOrOptions Optional name of the header when sent over HTTP or header options.
24
+ * By default the header name will be the property name converted from camelCase to kebab-case. (e.g. `contentType` -> `content-type`)
25
25
  *
26
26
  * @example
27
27
  *
28
28
  * ```typespec
29
- * op read(@header accept: string): {@header("E-Tag") eTag: string};
29
+ * op read(@header accept: string): {@header("ETag") eTag: string};
30
30
  * op create(@header({name: "X-Color", format: "csv"}) colors: string[]): void;
31
31
  * ```
32
32
  *
33
33
  * @example Implicit header name
34
34
  *
35
35
  * ```typespec
36
- * op read(): {@header eTag: string}; // headerName: e-tag
37
36
  * op read(): {@header contentType: string}; // headerName: content-type
37
+ * op update(@header ifMatch: string): void; // headerName: if-match
38
38
  * ```
39
39
  */
40
40
  extern dec header(target: ModelProperty, headerNameOrOptions?: string | HeaderOptions);
@@ -107,7 +107,7 @@ extern dec body(target: ModelProperty);
107
107
  extern dec statusCode(target: ModelProperty);
108
108
 
109
109
  /**
110
- * Specify the http verb for the target operation to be `GET`.
110
+ * Specify the HTTP verb for the target operation to be `GET`.
111
111
  *
112
112
  * @example
113
113
  *
@@ -118,7 +118,7 @@ extern dec statusCode(target: ModelProperty);
118
118
  extern dec get(target: Operation);
119
119
 
120
120
  /**
121
- * Specify the http verb for the target operation to be `PUT`.
121
+ * Specify the HTTP verb for the target operation to be `PUT`.
122
122
  *
123
123
  * @example
124
124
  *
@@ -129,7 +129,7 @@ extern dec get(target: Operation);
129
129
  extern dec put(target: Operation);
130
130
 
131
131
  /**
132
- * Specify the http verb for the target operation to be `POST`.
132
+ * Specify the HTTP verb for the target operation to be `POST`.
133
133
  *
134
134
  * @example
135
135
  *
@@ -140,7 +140,7 @@ extern dec put(target: Operation);
140
140
  extern dec post(target: Operation);
141
141
 
142
142
  /**
143
- * Specify the http verb for the target operation to be `PATCH`.
143
+ * Specify the HTTP verb for the target operation to be `PATCH`.
144
144
  *
145
145
  * @example
146
146
  *
@@ -151,7 +151,7 @@ extern dec post(target: Operation);
151
151
  extern dec patch(target: Operation);
152
152
 
153
153
  /**
154
- * Specify the http verb for the target operation to be `DELETE`.
154
+ * Specify the HTTP verb for the target operation to be `DELETE`.
155
155
  *
156
156
  * @example
157
157
  *
@@ -162,7 +162,7 @@ extern dec patch(target: Operation);
162
162
  extern dec delete(target: Operation);
163
163
 
164
164
  /**
165
- * Specify the http verb for the target operation to be `HEAD`.
165
+ * Specify the HTTP verb for the target operation to be `HEAD`.
166
166
  * @example
167
167
  *
168
168
  * ```typespec
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typespec/http",
3
- "version": "0.47.0-dev.2",
3
+ "version": "0.47.0-dev.4",
4
4
  "author": "Microsoft Corporation",
5
5
  "description": "TypeSpec HTTP protocol binding",
6
6
  "homepage": "https://github.com/microsoft/typespec",