Skip to content

feat: add TS examples to API GQL docs #5059

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 21, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 86 additions & 6 deletions src/fragments/lib/graphqlapi/js/authz.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,40 @@ In order to use this feature with the Amplify GraphQL Client the `API.graphql({.

This is an example of using `AWS_IAM` as an authorization mode:

<BlockSwitcher>
<Block name="TypeScript">

```ts
import { API, GraphQLQuery, GRAPHQL_AUTH_MODE } from '@aws-amplify/api';
import * as mutations from './graphql/mutations';
import { CreateTodoMutation } from './API';

// Creating a post is restricted to IAM
const createdTodo = await API.graphql<GraphQLQuery<CreateTodoMutation>>({
query: mutations.createTodo,
variables: { input: todoDetails },
authMode: GRAPHQL_AUTH_MODE.AWS_IAM
});
```

</Block>
<Block name="JavaScript">

```js
import { API, GRAPHQL_AUTH_MODE } from '@aws-amplify/api';
import * as mutations from './graphql/mutations';

// Creating a post is restricted to IAM
const createdTodo = await API.graphql({
query: queries.createTodo,
query: mutations.createTodo,
variables: {input: todoDetails},
authMode: 'AWS_IAM'
authMode: GRAPHQL_AUTH_MODE.AWS_IAM
});
```

</Block>
</BlockSwitcher>

Previous examples uses `graphqlOperation` function. That function only creates an object with two attributes `query` and `variables`. In order to use `authMode` you need to pass this object as is mentioned on the previous example.

<Callout>
Expand All @@ -40,27 +65,82 @@ You can implement your own custom API authorization logic using an AWS Lambda fu
If you are using a Lambda function as an authorization mode with your AppSync API, you will need to pass an authentication token with each API request and will need to manage token refresh in your application.

The following example assumes `AWS_LAMBDA` is configured as the default authentication type for your API:

<BlockSwitcher>
<Block name="TypeScript">

```ts
// ...

const getAuthToken = () => 'myAuthToken';
const lambdaAuthToken = getAuthToken();

const createdTodo = await API.graphql<GraphQLQuery<CreateTodoMutation>>({
query: mutations.createTodo,
variables: {input: todoDetails},
authToken: lambdaAuthToken
});
```

</Block>

<Block name="JavaScript">
```js
// ...

const getAuthToken = () => 'myAuthToken';
const lambdaAuthToken = getAuthToken();

const createdTodo = await API.graphql({
query: queries.createTodo,
query: mutations.createTodo,
variables: {input: todoDetails},
authToken: lambdaAuthToken
});
```

</Block>
</BlockSwitcher>

If you have a different default authentication type and would like to use `AWS_LAMBDA` with a request:
```javascript

<BlockSwitcher>
<Block name="TypeScript">

```ts
// ...
import { GRAPHQL_AUTH_MODE } from '@aws-amplify/api';
import { CreateTodoMutation } from './API';

const getAuthToken = () => 'myAuthToken';
const lambdaAuthToken = getAuthToken();

const createdTodo = await API.graphql<GraphQLQuery<CreateTodoMutation>>({
query: mutations.createTodo,
variables: {input: todoDetails},
authMode: GRAPHQL_AUTH_MODE.AWS_LAMBDA,
authToken: lambdaAuthToken
});
```

</Block>

<Block name="JavaScript">

```js
// ...
import { GRAPHQL_AUTH_MODE } from '@aws-amplify/api';

const getAuthToken = () => 'myAuthToken';
const lambdaAuthToken = getAuthToken();

const createdTodo = await API.graphql({
query: queries.createTodo,
query: mutations.createTodo,
variables: {input: todoDetails},
authMode: 'AWS_LAMBDA',
authMode: GRAPHQL_AUTH_MODE.AWS_LAMBDA,
authToken: lambdaAuthToken
});
```

</Block>
</BlockSwitcher>

16 changes: 8 additions & 8 deletions src/fragments/lib/graphqlapi/js/cancel-request.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ You may cancel any query or mutation request made through API category by keepin
const promise = API.graphql(graphqlOperation(...));

try {
await promise;
await promise;
} catch (error) {
console.log(error);
// If the error is because the request was cancelled you can confirm here.
if(API.isCancel(error)) {
console.log(error.message); // "my message for cancellation"
// handle user cancellation logic
}
console.log(error);
// If the error is because the request was cancelled you can confirm here.
if (API.isCancel(error)) {
console.log(error.message); // "my message for cancellation"
// handle user cancellation logic
}
}

...
Expand All @@ -26,7 +26,7 @@ You need to ensure that the promise returned from `API.graphql()` has not been m

```javascript
async function makeAPICall() {
return API.graphql(graphqlOperation(...));
return API.graphql(graphqlOperation(...));
}
const promise = makeAPICall();

Expand Down
88 changes: 83 additions & 5 deletions src/fragments/lib/graphqlapi/js/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,30 @@ Now that the GraphQL API has deployed, it’s time to learn how to interact with

- __Mutations__ - write data to the API (create, update, delete operations)

<BlockSwitcher>
<Block name="TypeScript">

```ts
import { API, graphqlOperation } from 'aws-amplify';
import { createTodo, updateTodo, deleteTodo } from './graphql/mutations';
import { GraphQLQuery } from '@aws-amplify/api';
import { CreateTodoInput, CreateTodoMutation, UpdateTodoMutation, DeleteTodoMutation } from './API';

const todo: CreateTodoInput = { name: "My first todo", description: "Hello world!" };

/* create a todo */
await API.graphql<GraphQLQuery<CreateTodoMutation>>(graphqlOperation(createTodo, {input: todo}));

/* update a todo */
await API.graphql<GraphQLQuery<UpdateTodoMutation>>(graphqlOperation(updateTodo, { input: { id: todoId, name: "Updated todo info" }}));

/* delete a todo */
await API.graphql<GraphQLQuery<DeleteTodoMutation>>(graphqlOperation(deleteTodo, { input: { id: todoId }}));
```

</Block>
<Block name="JavaScript">

```js
import { API, graphqlOperation } from 'aws-amplify';
import { createTodo, updateTodo, deleteTodo } from './graphql/mutations';
Expand All @@ -88,35 +112,89 @@ await API.graphql(graphqlOperation(updateTodo, { input: { id: todoId, name: "Upd
/* delete a todo */
await API.graphql(graphqlOperation(deleteTodo, { input: { id: todoId }}));
```

</Block>
</BlockSwitcher>

- __Queries__ - read data from the API (list, get operations)

<BlockSwitcher>
<Block name="TypeScript">

```ts
import { API, graphqlOperation } from 'aws-amplify';
import { GraphQLQuery } from '@aws-amplify/api';
import { listTodos } from './graphql/queries';
import { ListTodosQuery } from './API';

const todos = await API.graphql<GraphQLQuery<ListTodosQuery>>(graphqlOperation(listTodos));
```

</Block>


<Block name="JavaScript">

```js
import { API, graphqlOperation } from 'aws-amplify';
import { listTodos } from './graphql/queries';

const todos = await API.graphql(graphqlOperation(listTodos));
```

</Block>
</BlockSwitcher>

- __Subscriptions__ - subscribe to changes in data for real-time functionality (onCreate, onUpdate, onDelete)

<BlockSwitcher>
<Block name="TypeScript">

```ts
import { API, graphqlOperation } from 'aws-amplify';
import { GraphQLSubscription } from '@aws-amplify/api';
import { onCreateTodo } from './graphql/subscriptions';
import { OnCreateTodoSubscription } from './API';

// Subscribe to creation of Todo
const sub = API.graphql<GraphQLSubscription<OnCreateTodoSubscription>>(
graphqlOperation(onCreateTodo)
).subscribe({
next: (payload) => {
const createdTodo = payload.value.data?.onCreateTodo;
console.log(createdTodo);
}
});

// Stop receiving data updates from the subscription
sub.unsubscribe();
```

</Block>

<Block name="JavaScript">

```js
import { API, graphqlOperation } from 'aws-amplify';
import { onCreateTodo } from './graphql/subscriptions';

// Subscribe to creation of Todo
const subscription = API.graphql(
const sub = API.graphql(
graphqlOperation(onCreateTodo)
).subscribe({
next: (todoData) => {
console.log(todoData);
// Do something with the data
next: (payload) => {
const createdTodo = payload.value.data?.onCreateTodo;
console.log(createdTodo);
}
});

// Stop receiving data updates from the subscription
subscription.unsubscribe();
sub.unsubscribe();
```

</Block>
</BlockSwitcher>

### Updating Your GraphQL Schema

When you create a GraphQL backend with the CLI, the schema definition for your backend data structure is saved in one of two places:
Expand Down
2 changes: 1 addition & 1 deletion src/fragments/lib/graphqlapi/js/js-configure.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Add Amplify to your app with `yarn` or `npm`:
npm install aws-amplify
```

In your app's entry point i.e. App.js, import and load the configuration file:
In your app's entry point i.e. App.ts or App.js, import and load the configuration file:

```javascript
import { Amplify, API, graphqlOperation } from 'aws-amplify';
Expand Down
Loading