@typespec/rest 0.47.0-dev.1 → 0.47.0

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 (2) hide show
  1. package/README.md +287 -93
  2. package/package.json +8 -9
package/README.md CHANGED
@@ -1,134 +1,328 @@
1
- # TypeSpec REST Library
1
+ # @typespec/rest
2
2
 
3
- This package provides [TypeSpec](https://github.com/microsoft/TypeSpec) decorators, models, and interfaces to describe APIs using the [REST style](https://en.wikipedia.org/wiki/Representational_state_transfer). These building blocks make defining REST resources and operations based on standard patterns extremely simple.
3
+ TypeSpec REST protocol binding
4
4
 
5
5
  ## Install
6
6
 
7
- In your TypeSpec project root
8
-
9
7
  ```bash
10
8
  npm install @typespec/rest
11
9
  ```
12
10
 
13
- ## Usage
11
+ ## Decorators
12
+
13
+ ### TypeSpec.Rest
14
+
15
+ - [`@action`](#@action)
16
+ - [`@actionSeparator`](#@actionseparator)
17
+ - [`@autoRoute`](#@autoroute)
18
+ - [`@collectionAction`](#@collectionaction)
19
+ - [`@copyResourceKeyParameters`](#@copyresourcekeyparameters)
20
+ - [`@createsOrReplacesResource`](#@createsorreplacesresource)
21
+ - [`@createsOrUpdatesResource`](#@createsorupdatesresource)
22
+ - [`@createsResource`](#@createsresource)
23
+ - [`@deletesResource`](#@deletesresource)
24
+ - [`@listsResource`](#@listsresource)
25
+ - [`@parentResource`](#@parentresource)
26
+ - [`@readsResource`](#@readsresource)
27
+ - [`@resource`](#@resource)
28
+ - [`@segment`](#@segment)
29
+ - [`@segmentOf`](#@segmentof)
30
+ - [`@updatesResource`](#@updatesresource)
14
31
 
15
- ```TypeSpec
16
- import "@typespec/rest";
32
+ #### `@action`
17
33
 
18
- using TypeSpec.Rest;
34
+ Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my-action)
35
+
36
+ ```typespec
37
+ @TypeSpec.Rest.action(name?: valueof string)
19
38
  ```
20
39
 
21
- See [Http and rest](https://microsoft.github.io/typespec/docs/standard-library/rest/).
40
+ ##### Target
22
41
 
23
- ## Library Tour
42
+ `Operation`
24
43
 
25
- `@typespec/rest` library defines of the following artifacts:
44
+ ##### Parameters
26
45
 
27
- - [TypeSpec HTTP/Rest Library](#typespec-httprest-library)
28
- - [Install](#install)
29
- - [Usage](#usage)
30
- - [Library Tour](#library-tour)
31
- - [Models](#models)
32
- - [Decorators](#decorators)
33
- - [Interfaces](#interfaces)
34
- - [See also](#see-also)
46
+ | Name | Type | Description |
47
+ | ---- | ----------------------- | ----------------------------------------------------------------------------- |
48
+ | name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. |
35
49
 
36
- ## Models
50
+ #### `@actionSeparator`
37
51
 
38
- | Model | Notes |
39
- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
40
- | KeysOf<T> | Dynamically gathers keys of the model type T. |
41
- | Page<T> | A model defines page of T which includes an array of T and optional next link. |
42
- | ParentKeysOf<T> | Dynamically gathers parent keys of the model type T, which are referenced with `@parentResource` decorator. |
43
- | ResourceError | The default error response for resource operations that includes <br> `code: int32` and `message string`. |
44
- | ResourceParameters&lt;TResource> | Represents operation parameters for resource TResource. Default to KeysOf&lt;T>. |
45
- | ResourceCollectionParameters&lt;TResource> | Represents collection operation parameters for resource TResource. Default to ParentKeysOf&lt;T> |
46
- | ResourceCreatedResponse&lt;T> | Resource create operation completed successfully. |
47
- | ResourceDeletedResponse | Resource deleted successfully. |
52
+ Defines the separator string that is inserted before the action name in auto-generated routes for actions.
48
53
 
49
- ## Decorators
54
+ ```typespec
55
+ @TypeSpec.Rest.actionSeparator(seperator: valueof / | : | /:)
56
+ ```
50
57
 
51
- The `@typespec/rest` library defines the following decorators in `TypeSpec.Rest` namespace:
58
+ ##### Target
52
59
 
53
- | Declarator | Scope | Syntax |
54
- | ------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
55
- | @discriminator | models | Syntax:<br> `@discriminator(kindString)` <br><br>Note:<br> `@discriminator` allows defining polymorphic models to be used by API as parameters and return types. In many strongly typed languages, they are expressed as inheritance. |
56
- | @resource | Model | Syntax:<br> `@resource(collectionName)` <br><br>Note:<br> This decorator is to used to mark a model as a resource type with a name for the type's collection. |
57
- | @readsResource | operations | Syntax:<br> `@readsResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the Read operation for a particular resource. |
58
- | @createsResource | operations | Syntax:<br> `@createsResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the Create operation for a particular resource. |
59
- | @createsOrUpdatesResource | operations | Syntax:<br> `@createsOrUpdatesResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the CreatesOrUpdate operation for a particular resource. |
60
- | @updatesResource | operations | Syntax:<br> `@updatesResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the Update operation for a particular resource. |
61
- | @deletesResource | operations | Syntax:<br> `@deletesResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the Delete operation for a particular resource. |
62
- | @listsResource | operations | Syntax:<br> `@listsResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the List operation for a particular resource. |
63
- | @parentResource | models | Syntax:<br> `@parentResource(parentModelTypeReference)` <br><br>Note:<br> `@parentResource` marks a model property with a reference to its parent resource type. The first argument should be a reference to a model type which will be treated as the parent type of the target model type. This will cause the `@key` properties of all parent types of the target type to show up in operations of the `Resource*<T>` interfaces defined in this library. |
64
- | @segment | model properties, operation parameters | Syntax:<br> `@segment(segmentString)` <br><br>Note:<br>`@segment` defines the preceding path segment for a `@path` parameter in auto-generated routes. The first argument should be a string that will be inserted into the operation route before the path parameter's name field. For example: <br> `op getUser(@path @segment("users") userId: string): User` <br> will produce the route `/users/{userId}`. |
65
- | @segmentOf | models | Syntax:<br> `@segment(segmentString)` <br><br>Note:<br>`@segmentOf` returns the URL segment of a given model if it has `@segment` and `@key` decorator. |
66
- | @segmentSeparator | model properties, operation parameters, or operations | Syntax:<br> `@segmentSeparator(separatorString)` <br><br>Note:<br> `@segmentSeparator` defines the separator string that is inserted between the target's `@segment` and the preceding route path in auto-generated routes. <br> The first argument should be a string that will be inserted into the operation route before the target's `@segment` value. Can be a string of any length. Defaults to `/`. |
67
- | @actionSeparator | model properties, operation parameters, or operations | Syntax:<br> `@actionSeparator(separatorString)` <br><br>Note:<br> `@actionSeparator` defines the separator string that is inserted before the action name in auto-generated routes for actions. |
68
- | @autoRoute | operations | Syntax:<br> `@autoRoute()` <br><br>Note:<br>`@autoRoute` enables automatic route generation for an operation, namespace, or interface. <br> When applied to an operation, it automatically generates the operation's route based on path parameter metadata. When applied to a namespace or interface, it causes all operations under that scope to have auto-generated routes. |
60
+ `union Model | ModelProperty | Operation`
69
61
 
70
- ## Interfaces
62
+ ##### Parameters
71
63
 
72
- These standard interfaces defines resource operations in basic building blocks that you can expose on the resources. You can use `extends` to compose the operations to meet the exact needs of your resource APIs.
64
+ | Name | Type | Description |
65
+ | --------- | ---------------------------- | ---------------------------------------------------------------- |
66
+ | seperator | `valueof union / \| : \| /:` | Seperator seperating the action segment from the rest of the url |
73
67
 
74
- For example, for below `Widget` model
68
+ #### `@autoRoute`
75
69
 
70
+ This interface or operation should resolve its route automatically. To be used with resource types where the route segments area defined on the models.
71
+
72
+ ```typespec
73
+ @TypeSpec.Rest.autoRoute
76
74
  ```
77
- @resource("widgets")
78
- model Widget {
79
- @key id: string;
80
- name: string;
75
+
76
+ ##### Target
77
+
78
+ `union Interface | Operation`
79
+
80
+ ##### Parameters
81
+
82
+ None
83
+
84
+ ##### Examples
85
+
86
+ ```typespec
87
+ @autoRoute
88
+ interface Pets {
89
+ get(@segment("pets") @path id: string): void; //-> route: /pets/{id}
81
90
  }
82
91
  ```
83
92
 
84
- - `Widget` resource supports full CRUDL operations.
93
+ #### `@collectionAction`
85
94
 
86
- ```TypeSpec
87
- interface WidgetService extends Resource.ResourceOperations<Widget, Error>;
95
+ Specify this operation is a collection action. (Scopped to a resource, /pets/my-action)
96
+
97
+ ```typespec
98
+ @TypeSpec.Rest.collectionAction(resourceType: Model, name?: valueof string)
88
99
  ```
89
100
 
90
- - `Widget` resource supports only CRD operations.
101
+ ##### Target
91
102
 
92
- ```TypeSpec
93
- interface WidgetService
94
- extends Resource.ResourceRead<Widget, Error>,
95
- Resource.ResourceCreate<Widget, Error>,
96
- Resource.ResourceDelete<Widget, Error> {
97
- }
103
+ `Operation`
104
+
105
+ ##### Parameters
106
+
107
+ | Name | Type | Description |
108
+ | ------------ | ----------------------- | ----------------------------------------------------------------------------- |
109
+ | resourceType | `Model` | Resource marked with |
110
+ | name | `valueof scalar string` | Name of the action. If not specified, the name of the operation will be used. |
111
+
112
+ #### `@copyResourceKeyParameters`
113
+
114
+ Copy the resource key parameters on the model
115
+
116
+ ```typespec
117
+ @TypeSpec.Rest.copyResourceKeyParameters(filter?: valueof string)
118
+ ```
119
+
120
+ ##### Target
121
+
122
+ `Model`
123
+
124
+ ##### Parameters
125
+
126
+ | Name | Type | Description |
127
+ | ------ | ----------------------- | ------------------------------------- |
128
+ | filter | `valueof scalar string` | Filter to exclude certain properties. |
129
+
130
+ #### `@createsOrReplacesResource`
131
+
132
+ Specify that this is a CreateOrReplace operation for a given resource.
133
+
134
+ ```typespec
135
+ @TypeSpec.Rest.createsOrReplacesResource(resourceType: Model)
136
+ ```
137
+
138
+ ##### Target
139
+
140
+ `Operation`
141
+
142
+ ##### Parameters
143
+
144
+ | Name | Type | Description |
145
+ | ------------ | ------- | -------------------- |
146
+ | resourceType | `Model` | Resource marked with |
147
+
148
+ #### `@createsOrUpdatesResource`
149
+
150
+ Specify that this is a CreatesOrUpdate operation for a given resource.
151
+
152
+ ```typespec
153
+ @TypeSpec.Rest.createsOrUpdatesResource(resourceType: Model)
154
+ ```
155
+
156
+ ##### Target
157
+
158
+ `Operation`
159
+
160
+ ##### Parameters
161
+
162
+ | Name | Type | Description |
163
+ | ------------ | ------- | -------------------- |
164
+ | resourceType | `Model` | Resource marked with |
165
+
166
+ #### `@createsResource`
167
+
168
+ Specify that this is a Create operation for a given resource.
169
+
170
+ ```typespec
171
+ @TypeSpec.Rest.createsResource(resourceType: Model)
172
+ ```
173
+
174
+ ##### Target
175
+
176
+ `Operation`
177
+
178
+ ##### Parameters
179
+
180
+ | Name | Type | Description |
181
+ | ------------ | ------- | -------------------- |
182
+ | resourceType | `Model` | Resource marked with |
183
+
184
+ #### `@deletesResource`
185
+
186
+ Specify that this is a Delete operation for a given resource.
187
+
188
+ ```typespec
189
+ @TypeSpec.Rest.deletesResource(resourceType: Model)
98
190
  ```
99
191
 
100
- -
192
+ ##### Target
101
193
 
102
- | Interfaces | Notes |
103
- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
104
- | ResourceRead&lt;TResource, TError> | Resource GET operation |
105
- | ResourceCreateOrUpdate&lt;TResource, TError> | Resource PUT operation |
106
- | ResourceCreate&lt;TResource, TError> | Resource POST operation |
107
- | ResourceUpdate&lt;TResource, TError> | Resource PATCH operation |
108
- | ResourceDelete&lt;TResource, TError> | Resource DEL operation |
109
- | ResourceList&lt;TResource, TError> | Resource LIST operation which is a GET operation from a parent resource. |
110
- | ResourceInstanceOperations&lt;TResource, TError> | Combines resource GET + PATCH + DEL operations |
111
- | ResourceCollectionOperations&lt;TResource, TError> | Combines resource POST + LIST operations |
112
- | ResourceOperations&lt;TResource, TError> | Combines resource instance and collection operations. Includes GET + PATCH + DEL + POST + LIST |
113
- | SingletonResourceRead&lt;TSingleton, TResource, TError> | Singleton resource GET operation. |
114
- | SingletonResourceUpdate&lt;TSingleton, TResource, TError> | Singleton resource PATCH operation. |
115
- | SingletonResourceOperations&lt;TSingleton, TResource, TError> | Combines resource GET + PATCH operations |
116
- | ExtensionResourceRead&lt;TExtension, TResource, TError> | Extension resource GET operation. |
117
- | ExtensionResourceCreateOrUpdate&lt;TExtension, TResource, TError> | Extension resource PUT operation |
118
- | ExtensionResourceCreate&lt;TExtension, TResource, TError> | Extension resource POST operation |
119
- | ExtensionResourceUpdate&lt;TExtension, TResource, TError> | Extension resource PATCH operation |
120
- | ExtensionResourceDelete&lt;TExtension, TResource, TError> | Extension resource GET operation |
121
- | ExtensionResourceList&lt;TExtension, TResource, TError> | Extension resource LIST operation which is a GET operation from a parent resource. |
122
- | ExtensionResourceInstanceOperations&lt;TExtension, TResource, TError> | Combines extension resource GET + PATCH + DEL operations. |
123
- | ExtensionResourceCollectionOperations&lt;TExtension, TResource, TError> | Combines extension resource POST + LIST operations. |
124
- | ExtensionResourceOperations&lt;TExtension, TResource, TError> | Combines extension resource instance and collection operations. Includes GET + PATCH + DEL + POST + LIST operations. |
194
+ `Operation`
125
195
 
126
- ## See also
196
+ ##### Parameters
127
197
 
128
- - [REST example](https://cadlplayground.z22.web.core.windows.net/?c=aW1wb3J0ICJAY2FkbC1sYW5nL3Jlc3QiOwoKQHNlcnZpY2VUaXRsZSgiV2lkZ2V0IFPGFSIpCm5hbWVzcGFjZSBEZW1vxxg7Cgp1c2luZyBDYWRsLkh0dHA7zBFSZXN0OwoKbW9kZWwgx1J7CiAgQGtleSBpZDogc3RyaW5nOwogIHdlaWdodDogaW50MzLEEWNvbG9yOiAicmVkIiB8ICJibHVlIjsKfQoKQGVycm9yx1ZFxAzFVWNvZGXLQG1lc3NhZ2XKZH0KCmludGVyZuQAxOYAjecAxiBleHRlbmRzIFJlc291cmNl5AC5xQlPcGVyYXRpb25zPMYyLMZxPsVyQOQA0EByb3V0ZSgiY3VzdG9tR2V0IikgyQwoKTrHa%2BQAgA%3D%3D):
129
- - [TypeSpec Getting Started](https://github.com/microsoft/typespec#getting-started)
130
- - [TypeSpec Website](https://microsoft.github.io/typespec)
198
+ | Name | Type | Description |
199
+ | ------------ | ------- | -------------------- |
200
+ | resourceType | `Model` | Resource marked with |
131
201
 
202
+ #### `@listsResource`
203
+
204
+ Specify that this is a List operation for a given resource.
205
+
206
+ ```typespec
207
+ @TypeSpec.Rest.listsResource(resourceType: Model)
132
208
  ```
133
209
 
210
+ ##### Target
211
+
212
+ `Operation`
213
+
214
+ ##### Parameters
215
+
216
+ | Name | Type | Description |
217
+ | ------------ | ------- | -------------------- |
218
+ | resourceType | `Model` | Resource marked with |
219
+
220
+ #### `@parentResource`
221
+
222
+ Mark model as a child of the given parent resource.
223
+
224
+ ```typespec
225
+ @TypeSpec.Rest.parentResource(parent: Model)
134
226
  ```
227
+
228
+ ##### Target
229
+
230
+ `Model`
231
+
232
+ ##### Parameters
233
+
234
+ | Name | Type | Description |
235
+ | ------ | ------- | ------------- |
236
+ | parent | `Model` | Parent model. |
237
+
238
+ #### `@readsResource`
239
+
240
+ Specify that this is a Read operation for a given resource.
241
+
242
+ ```typespec
243
+ @TypeSpec.Rest.readsResource(resourceType: Model)
244
+ ```
245
+
246
+ ##### Target
247
+
248
+ `Operation`
249
+
250
+ ##### Parameters
251
+
252
+ | Name | Type | Description |
253
+ | ------------ | ------- | -------------------- |
254
+ | resourceType | `Model` | Resource marked with |
255
+
256
+ #### `@resource`
257
+
258
+ Mark this model as a resource type with a name.
259
+
260
+ ```typespec
261
+ @TypeSpec.Rest.resource(collectionName: valueof string)
262
+ ```
263
+
264
+ ##### Target
265
+
266
+ `Model`
267
+
268
+ ##### Parameters
269
+
270
+ | Name | Type | Description |
271
+ | -------------- | ----------------------- | ---------------------- |
272
+ | collectionName | `valueof scalar string` | type's collection name |
273
+
274
+ #### `@segment`
275
+
276
+ Defines the preceding path segment for a
277
+
278
+ ```typespec
279
+ @TypeSpec.Rest.segment(name: valueof string)
280
+ ```
281
+
282
+ ##### Target
283
+
284
+ `union Model | ModelProperty | Operation`
285
+
286
+ ##### Parameters
287
+
288
+ | Name | Type | Description |
289
+ | ---- | ----------------------- | ---------------------------------------------------------------------------------------------- |
290
+ | name | `valueof scalar string` | Segment that will be inserted into the operation route before the path parameter's name field. |
291
+
292
+ ##### Examples
293
+
294
+ #### `@segmentOf`
295
+
296
+ Returns the URL segment of a given model if it has `@segment` and `@key` decorator.
297
+
298
+ ```typespec
299
+ @TypeSpec.Rest.segmentOf(type: Model)
300
+ ```
301
+
302
+ ##### Target
303
+
304
+ `Operation`
305
+
306
+ ##### Parameters
307
+
308
+ | Name | Type | Description |
309
+ | ---- | ------- | ------------ |
310
+ | type | `Model` | Target model |
311
+
312
+ #### `@updatesResource`
313
+
314
+ Specify that this is a Update operation for a given resource.
315
+
316
+ ```typespec
317
+ @TypeSpec.Rest.updatesResource(resourceType: Model)
318
+ ```
319
+
320
+ ##### Target
321
+
322
+ `Operation`
323
+
324
+ ##### Parameters
325
+
326
+ | Name | Type | Description |
327
+ | ------------ | ------- | -------------------- |
328
+ | resourceType | `Model` | Resource marked with |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typespec/rest",
3
- "version": "0.47.0-dev.1",
3
+ "version": "0.47.0",
4
4
  "author": "Microsoft Corporation",
5
5
  "description": "TypeSpec REST protocol binding",
6
6
  "homepage": "https://microsoft.github.io/typespec",
@@ -42,17 +42,17 @@
42
42
  "!dist/test/**"
43
43
  ],
44
44
  "peerDependencies": {
45
- "@typespec/compiler": "~0.46.0 || >=0.47.0-dev <0.47.0"
45
+ "@typespec/compiler": "~0.47.0"
46
46
  },
47
47
  "devDependencies": {
48
48
  "@types/mocha": "~10.0.1",
49
49
  "@types/node": "~18.11.9",
50
- "@typespec/compiler": "~0.46.0 || >=0.47.0-dev <0.47.0",
51
- "@typespec/http": "~0.46.0 || >=0.47.0-dev <0.47.0",
52
- "@typespec/eslint-config-typespec": "~0.46.0 || >=0.47.0-dev <0.47.0",
53
- "@typespec/library-linter": "~0.46.0 || >=0.47.0-dev <0.47.0",
54
- "@typespec/eslint-plugin": "~0.46.0 || >=0.47.0-dev <0.47.0",
55
- "@typespec/tspd": "~0.46.0 || >=0.47.0-dev <0.47.0",
50
+ "@typespec/compiler": "~0.47.0",
51
+ "@typespec/http": "~0.47.0",
52
+ "@typespec/eslint-config-typespec": "~0.47.0",
53
+ "@typespec/library-linter": "~0.47.0",
54
+ "@typespec/eslint-plugin": "~0.47.0",
55
+ "@typespec/tspd": "~0.46.0",
56
56
  "eslint": "^8.42.0",
57
57
  "mocha": "~10.2.0",
58
58
  "mocha-junit-reporter": "~2.2.0",
@@ -61,7 +61,6 @@
61
61
  "rimraf": "~5.0.1",
62
62
  "typescript": "~5.1.3"
63
63
  },
64
- "dependencies": {},
65
64
  "scripts": {
66
65
  "clean": "rimraf ./dist ./temp",
67
66
  "build": "tsc -p . && npm run lint-typespec-library",