diff --git a/docs/getting-started/azure-cosmos-db/authors.json b/docs/getting-started/azure-cosmos-db/authors.json new file mode 100644 index 0000000000..8aa27f4899 --- /dev/null +++ b/docs/getting-started/azure-cosmos-db/authors.json @@ -0,0 +1,39 @@ +[ + { + "id": "1", + "first_name": "Isaac", + "middle_name": "", + "last_name": "Asimov", + "books": [ + "1000", + "1001", + "1002", + "1003", + "1004", + "1005", + "1008" + ] + }, + { + "id": "2", + "first_name": "Robert", + "middle_name": "A", + "last_name": "Heinlein", + "books": [ + "1006", + "1007" + ] + }, + { + "id": "3", + "first_name": "Robert", + "middle_name": "", + "last_name": "Silvenberg", + "books": [ + "1008", + "1009", + "1010" + ] + } +] + diff --git a/docs/getting-started/azure-cosmos-db/books.json b/docs/getting-started/azure-cosmos-db/books.json new file mode 100644 index 0000000000..71a8272b11 --- /dev/null +++ b/docs/getting-started/azure-cosmos-db/books.json @@ -0,0 +1,141 @@ +[ + { + "id": "1000", + "title": "Foundation", + "authors": [ + { + "id": "1", + "first_name": "Isaac", + "middle_name": "", + "last_name": "Asimov" + } + ] + }, + { + "id": "1001", + "title": "Foundation and Empire", + "authors": [ + { + "id": "1", + "first_name": "Isaac", + "middle_name": "", + "last_name": "Asimov" + } + ] + }, + { + "id": "1002", + "title": "Second Foundation", + "authors": [ + { + "id": "1", + "first_name": "Isaac", + "middle_name": "", + "last_name": "Asimov" + } + ] + }, + { + "id": "1003", + "title": "Foundation's Edge", + "authors": [ + { + "id": "1", + "first_name": "Isaac", + "middle_name": "", + "last_name": "Asimov" + } + ] + }, + { + "id": "1004", + "title": "Foundation and Earth", + "authors": [ + { + "id": "1", + "first_name": "Isaac", + "middle_name": "", + "last_name": "Asimov" + } + ] + }, + { + "id": "1005", + "title": "Starship Troopers", + "authors": [ + { + "id": "1", + "first_name": "Isaac", + "middle_name": "", + "last_name": "Asimov" + } + ] + }, + { + "id": "1006", + "title": "Stranger in a Strange Land", + "authors": [ + { + "id": "2", + "first_name": "Isaac", + "middle_name": "", + "last_name": "Asimov" + } + ] + }, + { + "id": "1007", + "title": "Nightfall", + "authors": [ + { + "id": "2", + "first_name": "Robert", + "middle_name": "A", + "last_name": "Heinlein" + } + ] + }, + { + "id": "1008", + "title": "Nightwings", + "authors": [ + { + "id": "1", + "first_name": "Isaac", + "middle_name": "", + "last_name": "Asimov" + }, + { + "id": "3", + "first_name": "Robert", + "middle_name": "", + "last_name": "Silvenberg" + } + ] + }, + { + "id": "1009", + "title": "Across a Billion Years", + "authors": [ + { + "id": "3", + "first_name": "Robert", + "middle_name": "", + "last_name": "Silvenberg" + } + ] + }, + { + "id": "1010", + "title": "Across a Billion Years", + "authors": [ + { + "id": "3", + "first_name": "Robert", + "middle_name": "", + "last_name": "Silvenberg" + } + ] + } +] + diff --git a/samples/getting-started/library.azure-sql.sql b/docs/getting-started/azure-sql-db/library.azure-sql.sql similarity index 100% rename from samples/getting-started/library.azure-sql.sql rename to docs/getting-started/azure-sql-db/library.azure-sql.sql diff --git a/docs/getting-started/getting-started-azure-cosmos-db.md b/docs/getting-started/getting-started-azure-cosmos-db.md index 2f8b3b0fcd..65e5d6795c 100644 --- a/docs/getting-started/getting-started-azure-cosmos-db.md +++ b/docs/getting-started/getting-started-azure-cosmos-db.md @@ -2,71 +2,162 @@ Make sure you have read the [Getting Started](getting-started.md) document. -As mentioned before, this tutorial assumes that you have already a Cosmos DB database that can used as playground. +This tutorial assumes that you have already a [Cosmos DB SQL API database account](https://docs.microsoft.com/en-us/azure/cosmos-db/sql/create-cosmosdb-resources-portal#create-an-azure-cosmos-db-account) that can be used as a playground. -## Get the database connection string +## Get the Cosmos DB Account connection string -## Add Book and Author entities +You can obtain the connection string by navigating to your Azure Cosmos DB account page's key blade, and select Primary connection string. Copy the value to use in the Data API Builder. +![Cosmos DB connection string](../media/cosmos-connection.png) -## Start Data API builder for Azure SQL Database +You can also use Azure Cosmos DB emulator connection string if you are testing locally. The Azure Cosmos DB Emulator supports a [single fixed account and a well-known authentication key](https://docs.microsoft.com/en-us/azure/azure-sql/database/connect-query-content-reference-guide?view=azuresql) -From the `sample` folder, where you should be already, start Data API builder engine (make sure you are using Powershell): +The connection string looks like, ``` -./run-dab.bat library.config.json +AccountEndpoint=AccountEndpoint=https://localhost:8081/;AccountKey=REPLACEME; ``` -when you'll see something like +Once you have the connection string, add it to the configuration file you have created before. It will look like the following if you are using Azure Cosmos DB: +```json +"data-source": { + "database-type": "cosmos", + "connection-string": "AccountEndpoint=yourEndpoint;AccountKey=REPLACEME" +} ``` -Now listening on: http://localhost:5000 -Now listening on: https://localhost:5001 + +and add the relevant database name in the Cosmos DB specific section of the configuration file + +```json + "cosmos": { + "database": "PlaygroundDB", + } ``` -then the engine is running. +## Create the database containers -## Query the endpoints +Create the necessary database containers needed to represent Authors and Books. -Now that Data API builder engine is running, you can use your favourite REST client (Postman or Insomnia, for example) to query the REST or the GraphQL endpoints. +- `authors`: Collection containing authors with 'id' as the partition key +- `books`: Collection containing books with 'id' as the partition key -### REST Endpoint +Read more about [choosing partition key](https://docs.microsoft.com/en-us/azure/cosmos-db/partitioning-overview#choose-partitionkey) and [data modelling](https://docs.microsoft.com/en-us/azure/cosmos-db/sql/modeling-data) + +Once the containers are created, you can import the sample data which are placed in the 'azure-cosmos-db' folder to the respective collections by using the [Data Import Tool](https://docs.microsoft.com/en-us/azure/cosmos-db/import-data#JSON). -REST endpoint is made available at the path: +## Add Book and Author entities +We want to expose the books and the authors collections so that they can be used via GraphQL. For doing that, all we need is to add the related information to the entities section of the configuration file. + +> **NOTE**: REST operations are not supported for Cosmos DB via the +> Data API Builder, You can use the existing [REST API](https://docs.microsoft.com/en-us/rest/api/cosmos-db/) + +Start by adding the `author` entity: + +```json + "entities": { + "author": { + "source": "authors", + "rest": false, + "graphql": true, + "permissions": [ + { + "role": "anonymous", + "actions": [ "*" ] + } + ] + } ``` -/api/ + +within the `entities` object you can create any entity with any name (as long as it is valid for GraphQL). The name `author`, in this case, will be used to build the GraphQL type. Within the entity you have the `source` element that specifies which container contains the entity data. In our case it is `authors`. + +> **NOTE**: Entities names are case sensitive and they will be exposed via GraphQL as you have typed them. + +After that, you need to specify the permission for the exposed entity, so that you can be sure only those users making a request with the right claims will be able to access the entity and its data. In this getting started tutorial we're just allowing anyone, without the need to be authenticated, to perform all the CRUD operations to the `author` entity. + +You can also add the `book` entity now, applying the same concepts you just learnt for the `author` entity. Once you have added the `author` entity, the `entities` object of configuration file will look like the following: + +```json + "entities": { + "Author": { + "source": "authors", + "rest": false, + "graphql": true, + "permissions": [ + { + "role": "anonymous", + "actions": [ "*" ] + } + ] + }, + "Book": { + "source": "books", + "rest": false, + "graphql": true, + "permissions": [ + { + "role": "anonymous", + "actions": [ "*" ] + } + ] + } + } ``` +## Add Book and Author schema files -so if you want to get a list of all the available books you can simply run this GET request: +We need to expose the books and the authors collections so that they can be used via Graphql. Cosmos DB, being schema agnostic, we need to provide the schema definition for the collections. These schema definitions need to be added in the `schema.gql` file. +Start by adding the `author` and `book` schema: + +```graphql +type Author @model { + id : ID, + first_name : String, + middle_name: String, + last_name: String, + Books: [Book] +} + +type Book @model { + id : ID, + title : String, + Authors: [String] +} ``` -/api/Book -``` -The following HTTP verbs are supported: +Add the above schemas to the `samples/getting-started/azure-cosmos-db` schema.gql file. + +That's all you need at the moment. Data API builder is ready to be run. + +> **BEST PRACTICE**: It is recommeneded to use the *singular* form for entities names. For GraphQL, the Data API builder engine will automatically use the correct plural form to generate the final GraphQL schema whenever a *list* of entity items will be returned. More on this behaviour in the [GraphQL documentation](./../graphql.md). + +## Start Data API builder for Azure Cosmos DB + +From the `samples/getting-started` folder, start Data API builder engine (use): -- GET: return one or more items -- POST: create a new item -- PUT: update or create an item -- DELETE: delete an item +``` +./run-dab.cmd library.config.json +``` -Whenver you need to access a single item, you can get the item you want by specifying its primary key: +Use `run-dab.sh` if you are on Linux. After a few seconds, you'll see something like ``` -GET /api/Book/id/1000 +Now listening on: http://localhost:5000 +Now listening on: https://localhost:5001 ``` -The ability to filter by primary key is supported by all verbs with the exception of POST as that verb is used to create a new iteam and therefore searching an item by its primary key is not applicable. +The Data API builder engine is running and is ready to accept requests. -The GET verbs also support several query parameters that allows you to manipulate and refine the requested data: -- `$orderby`: defines how the returned data will be sorted -- `$first`: returns only the top `n` items -- `$filter`: filter the returned items -- `$select`: return only the selected columns -For more details on how they can be used, read refer to the [REST documentation](./docs/REST.md) +## Query the endpoints + +Now that the Data API builder engine is running, you can use your favourite REST client (Postman, Insomnia, etc.) to query the GraphQL endpoints. +### REST Endpoint + +Unlike other databases, Data API Builder for Azure Cosmos DB does not support generating REST endpoints because there is already a[REST API endpoint](https://docs.microsoft.com/en-us/rest/api/cosmos-db/) capability built-in to the Azure Cosmos DB service. + ### GraphQL endpoint GraphQL endpoint is available at @@ -75,11 +166,11 @@ GraphQL endpoint is available at /graphql ``` -Use a GraphQL-capable REST client like Postman or Insomina to query the database using full GraphQL introspection capabilities. For example: +Use a GraphQL-capable REST client like Postman or Insomnia to query the database using full GraphQL introspection capabilities and to get IntelliSense and validation. For example: ```graphql { - books(first: 5) { + books(first: 5, orderBy: { title: DESC }) { items { id title @@ -87,3 +178,35 @@ Use a GraphQL-capable REST client like Postman or Insomina to query the database } } ``` + +will return the first five books ordered by title in descending order. + +## GraphQL operations on entity relationships + +With your GraphQL endpoint operational, you probably want to take advantage of GraphQL's ability to handle complex requests.For example, you may want to get all the Books in your library along with the Authors they have written. In order to achieve that, you need to let Data API Builder know that you want that relationship to be available to be used in queries. We have defined the +data models in such a way that they can be queried at once. + +Using GraphQL you can now execute queries like: + +```graphql +{ + books(filter: { title: { eq: "Foundation" } }) + { + items { + id + title + authors { + + first_name + last_name + + } + } + } +} + +``` +This query will return List of books and its Authors. + +Congratulations, you have just created a fully working backend to support your modern applications! + diff --git a/docs/getting-started/getting-started-azure-sql-db.md b/docs/getting-started/getting-started-azure-sql-db.md index d693f7cf34..0680d57075 100644 --- a/docs/getting-started/getting-started-azure-sql-db.md +++ b/docs/getting-started/getting-started-azure-sql-db.md @@ -34,7 +34,7 @@ Once you have your connection string, add it to the configuration file you have ## Create the database objects -Create the database tables needed to represent Authors, Books and the many-to-many relationship between Authors and Books. You can find the `libray.azure-sql.sql` script that you can use to create three tables, along with sample data: +Create the database tables needed to represent Authors, Books and the many-to-many relationship between Authors and Books. You can find the `libray.azure-sql.sql` script in the 'azure-sql-db' folder that you can use to create three tables, along with sample data: - `dbo.authors`: Table containing authors - `dbo.books`: Table containing books @@ -44,7 +44,7 @@ Execute the script in the SQL Server or Azure SQL database you decided to use, s ## Add Book and Author entities -We want to expose the `books` and the `authors` table so that they can be used via REST or GraphQL. For doing that, all is needed is adding the related information to the `entities` section of the configuration file. +Now, you'll want to expose the `books` and the `authors` table as REST or GraphQL endpoints. To do that, add the following information to the `entities` section of the configuration file. Start by adding the `author` entity: @@ -99,7 +99,7 @@ that's all is needed at the moment. Data API builder is ready to be run. ## Start Data API builder for Azure SQL Database -From the `sample` folder, where you should be already, start Data API builder engine (use): +From the `samples/getting-started` folder, start Data API Builder engine : ``` ./run-dab.cmd library.config.json diff --git a/docs/getting-started/getting-started.md b/docs/getting-started/getting-started.md index 3151f61942..7fb2735c19 100644 --- a/docs/getting-started/getting-started.md +++ b/docs/getting-started/getting-started.md @@ -2,7 +2,7 @@ Welcome to this getting started tutorial that will guide you to have Data API builder for Azure Databases running locally on your machine as a first step, and then will guide you to deploy Data API builder for Azure Databases in an Azure Container Instance, so that at the end of the tutorial you'll have full knowledge of what's needed to run Data API builder for Azure Databases both on-prem and in Azure. -## Pre-Requisite +## Prerequisites As the Data API builder for Azure Databases generate REST and GraphQL endpoints for database objects, you need to have a database ready to be used. You can choose either a relational or non-relational database. @@ -55,7 +55,7 @@ In the `data-source` section you have to specify the database type and the conne `database-type` can be any of the following: - `mssql`: for Azure SQL DB, Azure SQL MI or SQL Server -- `cosmos`: for Azure Cosmos DB +- `cosmos`: for Azure Cosmos DB (SQL API) - `postgresql`: for PostgreSQL - `mariadb`: for MariaDB - `mysql`: for MySQL diff --git a/docs/media/cosmos-connection.png b/docs/media/cosmos-connection.png new file mode 100644 index 0000000000..c50704fa13 Binary files /dev/null and b/docs/media/cosmos-connection.png differ diff --git a/samples/getting-started/schema.gql b/samples/getting-started/schema.gql new file mode 100644 index 0000000000..e69de29bb2