docs: adds patterns documentation

Author: jbottigliero

documents/patterns.md

@@ -0,0 +1,19 @@
+## Service Version Support
+
+Some Globus services expose multiple API generations. The SDK surfaces these under a version namespace on the service object (e.g, `transfer.v2`).
+
+```ts
+import { transfer } from '@globus/sdk';
+
+await transfer.v2.bookmarks.getAll();
+await transfer.v2.bookmarks.get({ bookmark_id: '...' });
+await transfer.v2.bookmarks.create({ request: { data: { name, endpoint_id, path } } });
+await transfer.v2.bookmarks.update({ bookmark_id: '...', request: { data: { name } } });
+await transfer.v2.bookmarks.remove({ bookmark_id: '...' });
+
+// Service-specific imports are also available.
+import { bookmarks } from '@globus/sdk/tranfer/v2';
+import { getAll } from '@globus/sdk/tranfer/v2/bookmarks';
+```
+
+As of `v6.x.x` the methods on the default namespace _may_ contain mixed version usage. The default namespace will likely be removed, or more formally aliased to the "latest" version of a service resource in an upcoming major release (breaking change).

src/services/transfer/service/v2/bookmarks.ts

@@ -29,7 +29,7 @@ type GetResponse = GetOperation['responses']['200']['content']['application/json
 export const get = createServiceMethodFactory({
   service: ID,
   resource_server: RESOURCE_SERVERS.TRANSFER,
-  path: `/v2/bookmark/{bookmark_id}`,
+  path: `/v2/bookmarks/{bookmark_id}`,
 }).generate<
   {
     request?: {
@@ -46,7 +46,7 @@ type CreateResponse = CreateOperation['responses']['201']['content']['applicatio
 export const create = createServiceMethodFactory({
   service: ID,
   resource_server: RESOURCE_SERVERS.TRANSFER,
-  path: `/v2/bookmark`,
+  path: `/v2/bookmarks`,
   method: HTTP_METHODS.POST,
 }).generate<
   {
@@ -63,7 +63,7 @@ type UpdateResponse = UpdateOperation['responses']['200']['content']['applicatio
 export const update = createServiceMethodFactory({
   service: ID,
   resource_server: RESOURCE_SERVERS.TRANSFER,
-  path: `/v2/bookmark/{bookmark_id}`,
+  path: `/v2/bookmarks/{bookmark_id}`,
   method: HTTP_METHODS.PATCH,
 }).generate<
   {
@@ -80,7 +80,7 @@ type RemoveResponse = RemoveOperation['responses']['200'];
 export const remove = createServiceMethodFactory({
   service: ID,
   resource_server: RESOURCE_SERVERS.TRANSFER,
-  path: `/v2/bookmark/{bookmark_id}`,
+  path: `/v2/bookmarks/{bookmark_id}`,
   method: HTTP_METHODS.DELETE,
 }).generate<
   {

typedoc.json

@@ -8,6 +8,7 @@
     "./src/core/info/index.ts",
     "./src/core/authorization/index.ts"
   ],
+  "projectDocuments": ["documents/*.md"],
   "entryPointStrategy": "expand",
   "out": "docs"
 }