-
Notifications
You must be signed in to change notification settings - Fork 86
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
Suggesting a new graphql hol #110
Draft
reidav
wants to merge
1
commit into
Azure:main
Choose a base branch
from
reidav:feature/graphql
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,92 +1,114 @@ | ||
| --- | ||
| title: Calling Apis | ||
| title: Import GraphQL APIs | ||
| parent: Adding APIs | ||
| has_children: false | ||
| nav_order: 3 | ||
| --- | ||
|
|
||
| ## Import and test an existing GraphQL API | ||
|
|
||
| ## Calling API and testing Subscription Keys | ||
| Let's import a new GraphQL API, using the [Star Wars GraphQL API](https://graphql.org/swapi-graphql). | ||
|
|
||
| Let's add another API, the [Colors API](https://colors-api.azurewebsites.net/swagger/v1/swagger.json). | ||
| - Select **Add API**, under **define a new API**, select the **GraphQL** icon. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| - Create a new API with OpenAPI specification and import swagger from <https://colors-api.azurewebsites.net/swagger/v1/swagger.json>. | ||
| - This time we will choose to not provide API URL suffix. Without API URL suffix, there could be endpoint conflicts, you can always leverage [rewrite-uri](https://learn.microsoft.com/en-us/azure/api-management/api-management-transformation-policies#RewriteURL) policy to convert a request URL form to the form expected by the backend web service. | ||
| - In the dialog box, select **Full** and complete the required form field. | ||
|
|
||
|  | ||
|  | ||
|
|
||
|  | ||
|
|
||
| - We can test the newly-added API from the *Test* tab. Note the successful **200** response. | ||
| | Field | Description | | ||
| |----------------|-------| | ||
| | **Display name** | The name by which your GraphQL API will be displayed. | | ||
| | **Name** | Raw name of the GraphQL API. Automatically populates as you type the display name. | | ||
| | **GraphQL API endpoint** | The base URL with your GraphQL API endpoint name. <br /> For example: *`https://example.com/your-GraphQL-name`*. You can also use a common "Star Wars" GraphQL endpoint such as `https://graphql.org/swapi-graphql` as a demo. | | ||
| | **Upload schema** | Optionally select to browse and upload your schema file to replace the schema retrieved from the GraphQL endpoint (if available). | | ||
| | **Description** | Add a description of your API. | | ||
| | **URL scheme** | Select **HTTP**, **HTTPS**, or **Both**. Default selection: *Both*. | | ||
| | **API URL suffix**| Add a URL suffix to identify this specific API in this API Management instance. It has to be unique in this API Management instance. | | ||
| | **Base URL** | Uneditable field displaying your API base URL | | ||
| | **Tags** | Associate your GraphQL API with new or existing tags. | | ||
| | **Products** | Associate your GraphQL API with a product to publish it. | | ||
| | **Gateways** | Associate your GraphQL API with existing gateways. Default gateway selection: *Managed*. | | ||
| | **Version this API?** | Select to apply a versioning scheme to your GraphQL API. | | ||
|
|
||
|  | ||
| - Select **Create** | ||
| - After the API is created, browse the schema on the **Design** tab, in the **Frontend** section. | ||
|
|
||
| - Products can be configured after the API is initially created as well. On the *Settings* tab, set *Products* to include *Starter* and *Unlimited*, then press *Save*. | ||
|  | ||
|
|
||
|  | ||
| - Under **Query Editor**: | ||
| - Select at least one field or subfield from the list in the side menu. The fields and subfields you select appear in the query editor. | ||
|
|
||
| - Switch to the Developer portal and look at the *Colors* API. | ||
| - Try the *Get random color* operation. | ||
| - Notice the successful `200` response and the returned random color. | ||
| - Start typing in the query editor to compose a query. | ||
|
|
||
|  | ||
|  | ||
|
|
||
|  | ||
| - Select Send and view the generated response | ||
|
|
||
| ### Rate limit | ||
|  | ||
|
|
||
| API Management uses rate limiting to protect APIs from being overwhelmed and helps prevent exposure to DDoS attacks. As APIM sits in between your API and their callers, it effectively governs access to your APIs. | ||
| ## Define GraphQL API based on resolvers mapped to HTTP endpoints | ||
|
|
||
| We are going to use the [Colors](https://colors-web.azurewebsites.net) website to demonstrate how rate limiting is applied. The website displays 500 lights. Each light will randomly make a call to the Get random color API and then apply the returned color to the lights. | ||
| - Select **Add API**, under **define a new API**, select the **Synthetic GraphQL** icon. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| First, we need to enable CORS for the domain name of the frontend. To achieve this we have to do the following in APIM: | ||
| - Copy the following schema in a new file named myschema.graphql | ||
| ```typescript | ||
| type Query { | ||
| users: [User] | ||
| } | ||
|
|
||
| - On the sidemenu, click on `APIs`, then select the `All APIs` option. | ||
| - Inside the `Inbound processing` area you will see the `cors` policy, which we added in part 2 by pressing the `Enable Cors` button. | ||
| - Click on the pencil icon next to that policy to edit it. | ||
| type User { | ||
| name: String! | ||
| hair_color: String! | ||
| } | ||
| ``` | ||
|
|
||
|  | ||
| - In the dialog box, select **Full** and complete the required form field. Use the myschema.graphql file generated previously. | ||
|
|
||
| - Here we will see this form where we can add the domain name of our frontend `https://colors-web.azurewebsites.net` or the `*` for all domains. Press *Add allowed origin*, enter the URL, then press *Save*. | ||
|  | ||
|
|
||
|  | ||
| - Select **Create** | ||
|
|
||
| - After enabling CORS in APIM lets go back to our frontend <https://colors-web.azurewebsites.net> and follow these steps: | ||
| - After the API is created, browse the schema on the **Design tab**, in the **Frontend** section. | ||
|
|
||
| - Click on the hamburger menu next to *Colors* in the top left corner. | ||
| - Click on *Config*. | ||
| - Replace the *API URL* according to this format: <https://YOURAPIM.azure-api.net/colors/random> (e.g. https://apim-lab-pk.azure-api.net/colors/random). | ||
| - After setting the API URL correctly, press the hamburger menu again and go to *Home*. | ||
| - Press *Start* to see how the frontend is calling the api. You should see a *401* response, indicating an auth error. This happens as our API requires a subscription, but we have not yet entered a subscription key. | ||
| - In the **Backend** processing policy, configure the set-graphql-resolver policy to map a field in the schema to an existing HTTP endpoint. Namevalue can also be used for variables such as the backend url. | ||
|
|
||
|  | ||
| ```xml | ||
| <backend> | ||
| <set-graphql-resolver parent-type="Query" field="users"> | ||
| <http-data-source> | ||
| <http-request> | ||
| <set-method>GET</set-method> | ||
| <set-url>https://swapi.dev/api/people/</set-url> | ||
| </http-request> | ||
| <http-response> | ||
| <set-body template="liquid"> | ||
| [ {% raw %} | ||
| {% JSONArrayFor elem in body %} | ||
| { | ||
| "hair_color": "{{elem.hair_color}}", | ||
| "name": "{{elem.name}}" | ||
| } | ||
| {% endJSONArrayFor %} | ||
| ] {% endraw %} | ||
| </set-body> | ||
| </http-response> | ||
| </http-data-source> | ||
| </set-graphql-resolver> | ||
| <base /> | ||
| </backend> | ||
| ``` | ||
| - We can see the user entities has been resolved. | ||
|
|
||
| - The subscription keys can be fetched from the Developer Portal. Open the main Developer Portal page, then click on *Profile* in the top menu. | ||
| - Copy the following URL into Notepad, modify your APIM instance, then copy the URL, so that you have two of the same URLs. We will use them for the *Starter* and *Unlimited* pathways into APIM. | ||
| - `https://YOURAPIM.azure-api.net/colors/random?key=` | ||
| - Append the primary keys for both subscriptions - one key per URL - to get unique URLs for *Starter* and *Unlimited*. | ||
|
|
||
|  | ||
| ## Supported capabilities | ||
|
|
||
| - To see that *Unlimited* product has no rate limits: | ||
| - Configure the Colors website to use the Unlimited URL. | ||
| - Select [Start]. | ||
| - Notice there is no rate limit - every light is randomly and continuously updated. | ||
| Using API Management to expose your GraphQL APIs, you can : | ||
|
|
||
|  | ||
|
|
||
| - To see that *Starter* product is limited to 5 calls per minute: | ||
| - Configure the Colors website to use the Starter URL. | ||
| - Select [Start]. | ||
| - Notice that only 5 lights get colored. | ||
|
|
||
|  | ||
|
|
||
| - Try the same *Starter* URL directly in your web browser: | ||
| - Notice the error status / message returned. For example: `{ "statusCode": 429, "message": "Rate limit is exceeded. Try again in 53 seconds." }` | ||
|
|
||
|  | ||
| - Add a GraphQL endpoint or GraphQL schema as an API via the Azure portal, the Azure CLI, or other Azure tools. | ||
| - Augment or design a GraphQL API using information from REST or SOAP APIs, using HTTP resolvers for fields defined in a GraphQL schema. | ||
| - Secure GraphQL APIs by applying both existing access control policies and a GraphQL validation policy to secure and protect against GraphQL-specific attacks. | ||
| - Explore the schema and run test queries against the GraphQL APIs in the Azure and developer portals. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| --- | ||
| title: Calling Apis | ||
| parent: Adding APIs | ||
| has_children: false | ||
| nav_order: 3 | ||
| --- | ||
|
|
||
|
|
||
| ## Calling API and testing Subscription Keys | ||
|
|
||
| Let's add another API, the [Colors API](https://colors-api.azurewebsites.net/swagger/v1/swagger.json). | ||
|
|
||
|  | ||
|
|
||
| - Create a new API with OpenAPI specification and import swagger from <https://colors-api.azurewebsites.net/swagger/v1/swagger.json>. | ||
| - This time we will choose to not provide API URL suffix. Without API URL suffix, there could be endpoint conflicts, you can always leverage [rewrite-uri](https://learn.microsoft.com/en-us/azure/api-management/api-management-transformation-policies#RewriteURL) policy to convert a request URL form to the form expected by the backend web service. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| - We can test the newly-added API from the *Test* tab. Note the successful **200** response. | ||
|
|
||
|  | ||
|
|
||
| - Products can be configured after the API is initially created as well. On the *Settings* tab, set *Products* to include *Starter* and *Unlimited*, then press *Save*. | ||
|
|
||
|  | ||
|
|
||
| - Switch to the Developer portal and look at the *Colors* API. | ||
| - Try the *Get random color* operation. | ||
| - Notice the successful `200` response and the returned random color. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### Rate limit | ||
|
|
||
| API Management uses rate limiting to protect APIs from being overwhelmed and helps prevent exposure to DDoS attacks. As APIM sits in between your API and their callers, it effectively governs access to your APIs. | ||
|
|
||
| We are going to use the [Colors](https://colors-web.azurewebsites.net) website to demonstrate how rate limiting is applied. The website displays 500 lights. Each light will randomly make a call to the Get random color API and then apply the returned color to the lights. | ||
|
|
||
|  | ||
|
|
||
| First, we need to enable CORS for the domain name of the frontend. To achieve this we have to do the following in APIM: | ||
|
|
||
| - On the sidemenu, click on `APIs`, then select the `All APIs` option. | ||
| - Inside the `Inbound processing` area you will see the `cors` policy, which we added in part 2 by pressing the `Enable Cors` button. | ||
| - Click on the pencil icon next to that policy to edit it. | ||
|
|
||
|  | ||
|
|
||
| - Here we will see this form where we can add the domain name of our frontend `https://colors-web.azurewebsites.net` or the `*` for all domains. Press *Add allowed origin*, enter the URL, then press *Save*. | ||
|
|
||
|  | ||
|
|
||
| - After enabling CORS in APIM lets go back to our frontend <https://colors-web.azurewebsites.net> and follow these steps: | ||
|
|
||
| - Click on the hamburger menu next to *Colors* in the top left corner. | ||
| - Click on *Config*. | ||
| - Replace the *API URL* according to this format: <https://YOURAPIM.azure-api.net/colors/random> (e.g. https://apim-lab-pk.azure-api.net/colors/random). | ||
| - After setting the API URL correctly, press the hamburger menu again and go to *Home*. | ||
| - Press *Start* to see how the frontend is calling the api. You should see a *401* response, indicating an auth error. This happens as our API requires a subscription, but we have not yet entered a subscription key. | ||
|
|
||
|  | ||
|
|
||
| - The subscription keys can be fetched from the Developer Portal. Open the main Developer Portal page, then click on *Profile* in the top menu. | ||
| - Copy the following URL into Notepad, modify your APIM instance, then copy the URL, so that you have two of the same URLs. We will use them for the *Starter* and *Unlimited* pathways into APIM. | ||
| - `https://YOURAPIM.azure-api.net/colors/random?key=` | ||
| - Append the primary keys for both subscriptions - one key per URL - to get unique URLs for *Starter* and *Unlimited*. | ||
|
|
||
|  | ||
|
|
||
| - To see that *Unlimited* product has no rate limits: | ||
| - Configure the Colors website to use the Unlimited URL. | ||
| - Select [Start]. | ||
| - Notice there is no rate limit - every light is randomly and continuously updated. | ||
|
|
||
|  | ||
|
|
||
| - To see that *Starter* product is limited to 5 calls per minute: | ||
| - Configure the Colors website to use the Starter URL. | ||
| - Select [Start]. | ||
| - Notice that only 5 lights get colored. | ||
|
|
||
|  | ||
|
|
||
| - Try the same *Starter* URL directly in your web browser: | ||
| - Notice the error status / message returned. For example: `{ "statusCode": 429, "message": "Rate limit is exceeded. Try again in 53 seconds." }` | ||
|
|
||
|  |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just hide the "hello-world" part of the apim url, so the reader keep in mind that he must define a naming convention like I did in the "general update" PR.