{"id":1116,"date":"2022-01-18T10:20:17","date_gmt":"2022-01-18T18:20:17","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sql\/?p=1116"},"modified":"2022-01-18T10:41:32","modified_gmt":"2022-01-18T18:41:32","slug":"automatic-graphql-and-rest-endpoint-for-azure-sql-with-directus","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sql\/automatic-graphql-and-rest-endpoint-for-azure-sql-with-directus\/","title":{"rendered":"Automatic GraphQL and REST endpoint for Azure SQL with Directus"},"content":{"rendered":"<p><a href=\"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-content\/uploads\/sites\/56\/2022\/01\/pexels-nathan-salt-2549355.jpg\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-1119\" src=\"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-content\/uploads\/sites\/56\/2022\/01\/pexels-nathan-salt-2549355.jpg\" alt=\"Image pexels nathan salt 2549355\" width=\"1000\" height=\"750\" srcset=\"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-content\/uploads\/sites\/56\/2022\/01\/pexels-nathan-salt-2549355.jpg 1000w, https:\/\/devblogs.microsoft.com\/azure-sql\/wp-content\/uploads\/sites\/56\/2022\/01\/pexels-nathan-salt-2549355-300x225.jpg 300w, https:\/\/devblogs.microsoft.com\/azure-sql\/wp-content\/uploads\/sites\/56\/2022\/01\/pexels-nathan-salt-2549355-768x576.jpg 768w\" sizes=\"(max-width: 1000px) 100vw, 1000px\" \/><\/a><\/p>\n<p><div class=\"alert alert-info\"><p class=\"alert-divider\"><i class=\"fabric-icon fabric-icon--Info\"><\/i><strong>Guest Post<\/strong><\/p>This post has been originally written by Rijk van Zanten (<a href=\"https:\/\/twitter.com\/daniel2color\">@rijkvanzanten<\/a>), CTO &amp; Co-Founder <a href=\"https:\/\/twitter.com\/directus\">@Directus<\/a>. Thanks Rijk! <\/div><\/p>\n<p>Extremely performant and built entirely on Node.js, <a href=\"https:\/\/directus.io\/\">Directus<\/a> is an open-source Data Platform that enables anyone in an organization \u2014 from developers to data scientists to business users \u2014 to access and manage the database content that powers all your applications and digital experiences. It installs as a layer on top of your existing SQL database, mirroring its content and schema, so there is no need to migrate or alter your data. Once installed, you instantly get a dynamic API (REST and GraphQL) and no-code app that democratizes data so you can extract maximum value from it across your organization.<\/p>\n<p><img decoding=\"async\" class=\"alignnone size-full\" src=\"https:\/\/raw.githubusercontent.com\/Azure-Samples\/azure-sql-db-rest-graphql-directus\/main\/assets\/architecture.png\" alt=\"Directus + AzureSQL\" width=\"1536\" height=\"632\" \/><\/p>\n<p>Sounds interesting? Good!<\/p>\n<p>So, now you\u2019ve decided to get Directus up and running on Azure SQL, but don\u2019t have a lot of time to spend messing around with the installation. The good news is there\u2019s a quick and easy way to deploy and get started with Directus, and in this post, I\u2019ll show you how.<\/p>\n<p><span style=\"font-weight: 400;\">The fastest way to get up and running with Directus is by using <\/span><a href=\"https:\/\/docs.microsoft.com\/en-us\/samples\/azure-samples\/azure-sql-db-rest-graphql-directus\/azure-sql-db-rest-graphql-directus\/\"><span style=\"font-weight: 400;\">this sample implementation<\/span><\/a><span style=\"font-weight: 400;\">. To make it even easier, in this post, I\u2019ll demonstrate how to spin up a Directus instance running on Azure SQL and Azure App Service, beginning with setting up a local project working directory and configuring the connection to Azure SQL. Then, I\u2019ll show you how to host Directus itself on Azure App Service, making your app and APIs accessible from anywhere!\u00a0<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Prerequisites\u00a0<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">To get started, you\u2019ll need Node.js version 12.20 or later, and an Azure SQL database server that&#8217;s accessible from your local machine.<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Creating the Database\u00a0<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Here\u2019s how to create a Directus compatible Azure SQL database using CLI commands.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Create a resource group to hold the resources for this project:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">az group create --location eastus --name {GROUP_NAME}<\/pre>\n<p><span style=\"font-weight: 400;\">Create the database server: <\/span><\/p>\n<pre class=\"prettyprint\">az sql server create -l eastus -g {GROUP_NAME} --name {DB_SERVER_NAME} --admin user {DB_ADMIN_USER} --admin-password {DB_PASSWORD} --enable-public-network true<\/pre>\n<p><span style=\"font-weight: 400;\">Make sure to note the database name, username and password somewhere safe.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Create the database:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">az sql db create --resource-group {GROUP_NAME} --server {DB_SERVER_NAME} --name {DB_NAME} --service-objective Basic<\/pre>\n<p><span style=\"font-weight: 400;\">Allow your computer to access the database:<\/span><\/p>\n<pre class=\"prettyprint\">az sql server firewall-rule create --resource-group {GROUP_NAME} --server {DB_SERVER_NAME} --name allow-local-access --start-ip-address {YOUR_PUBLIC_IP} --end-ip-address {YOUR_PUBLIC_IP}<\/pre>\n<h2><span style=\"font-weight: 400;\">Creating the Project &amp; Installing Directus\u00a0<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Create a project directory, and install Directus by running:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">npm init directus-project .\/directus-example<\/pre>\n<p><span style=\"font-weight: 400;\">Then, in the prompts, enter:\u00a0<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Database Client: Microsoft SQL Server\u00a0<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Database host: {DB_SERVER_NAME}.database.windows.net\u00a0<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Port: 1433 (default)\u00a0<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Database Name: {DB_NAME}\u00a0<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Database User: {DB_ADMIN_USER}\u00a0<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Database Password: {DB_ADMIN_PASSWORD}\u00a0<\/span><\/li>\n<li style=\"font-weight: 400;\" aria-level=\"1\"><span style=\"font-weight: 400;\">Encrypt Connection: Yes\u00a0<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">Next, enter any email address\/password combination you&#8217;d like for the first user.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Once that&#8217;s done, you can navigate into the project folder and run <\/span><i><span style=\"font-weight: 400;\">npx directus start<\/span><\/i><span style=\"font-weight: 400;\"> to start Directus.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">By default, Directus will run on port 8055. Once you&#8217;ve started Directus, you can navigate to <em>localhost:8055<\/em> to open the admin app. Log in with the admin email and password\u00a0<\/span><span style=\"font-weight: 400;\">combination you&#8217;ve configured.\u00a0<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Creating the Data Model<\/span><b>\u00a0<\/b><\/h2>\n<p><span style=\"font-weight: 400;\">I\u2019ll keep it brief for this intro example. (For more in-depth information on what Directus has to offer, please refer to the Directus Documentation.)<\/span><\/p>\n<p><span style=\"font-weight: 400;\">In Directus, collections and fields correspond directly to tables and columns in the database. Every collection you create in Directus creates a table in the database and, similarly, every field you create will be a column in the database.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">When you open the admin app without having any existing collections, you&#8217;ll be prompted to create your first collection. I\u2019ll go with a collection named \u201carticles,\u201d but feel free to use whatever you\u2019d like!<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Once the collection is created, it&#8217;s time to add some fields. Go to <em>Settings &gt; Data Model &gt; [Articles]<\/em> and click \u201c<em>Create Field<\/em>\u201d. I\u2019ll stick to a regular input for now, but don&#8217;t hesitate to try out some of the other fields if you&#8217;re curious. Let\u2019s give this field a key of \u201c<em>title<\/em>\u201d, and hit Save.\u00a0<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Configuring Permissions\u00a0<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Now that you have spun up a very basic data model, you need to make sure only the correct people can access it. In this demo, I\u2019ll show you how to give public read\/write access to the \u201carticles\u201d table you\u2019ve created.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">To set up permissions for the public role, head to <em>Settings &gt; Roles &amp; Permissions &gt; Public<\/em>. Using the checkbox icons in the table, set both <em>Create<\/em> (plus) and <em>Read<\/em> (eye) to \u201c<em>All Access<\/em>\u201d. This will allow anybody outside of the service to create and read items from your \u201c<em>articles<\/em>\u201d table.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Directus has a powerful rule-based permissions system that you can use to fine-tune access control for your exact needs. The example above is only the tip of the iceberg! (For more information, refer to the Directus Documentation on permissions.)\u00a0<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Connecting Data\u00a0<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Now that you have a basic data model in place, with permissions for the outside world to\u00a0<\/span><span style=\"font-weight: 400;\">save and retrieve the data, you can start using the API. Directus ships with powerful RESTful and GraphQL APIs that beautifully wrap the raw power of Azure SQL, to let you interact with the data for your apps, websites, kiosks or whatever else you can think of!<\/span><\/p>\n<p><span style=\"font-weight: 400;\">With your local server running, you can start querying the API using curl or any other local request development tool you prefer.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Use this command to create an article: <\/span><\/p>\n<pre class=\"prettyprint\">curl localhost:8055\/items\/articles \\ \r\n-X POST \\ \r\n-H \"Content-Type: application\/json\" \\ \r\n-d \"{\\\"title\\\": \\\"Hello World!\\\"}\" \r\n<\/pre>\n<p><span style=\"font-weight: 400;\">Use this command to retrieve all articles:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">curl localhost:8055\/items\/articles<\/pre>\n<p><span style=\"font-weight: 400;\">Or if GraphQL, using, for example the GraphQL endpoint:<\/span><\/p>\n<pre class=\"prettyprint\">localhost:8055\/graphql<\/pre>\n<p><span style=\"font-weight: 400;\">is more of your taste:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">query {\u00a0\r\n\u00a0articles {\u00a0\r\n\u00a0title\u00a0\r\n\u00a0}\u00a0\r\n} \r\n<\/pre>\n<p>(You can use any desktop GraphQL client or the online interactive client: <a href=\"https:\/\/graphiql-online.com\/graphiql\">https:\/\/graphiql-online.com\/graphiql<\/a>)<\/p>\n<p><span style=\"font-weight: 400;\">The actions above are just a sample of what the APIs have to offer. For the sake of brevity in this quick introduction, I\u2019m skipping over the powerful query parameters that let you search, filter, sort, limit and nest relational data. To learn more about all the flexibility Directus&#8217;s APIs provide, refer to the Directus Documentation API Reference.\u00a0<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Going Live\u00a0<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">Directus runs on basically anything that can run Node. For the easiest deployment, I recommend using Azure App Service running the official Directus Docker Image. This allows you to run a highly available installation of Directus, without having to deal with server maintenance or any other manual intervention.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Take these steps to get started:<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Allow Azure services to reach the database:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">az sql server firewall-rule create --resource-group {GROUP_NAME} --server {DB_SERVER_NAME} --name allow-azure-services --start-ip-address 0.0.0.0 --end ip-address 0.0.0.0<\/pre>\n<p><span style=\"font-weight: 400;\">Create an App Service plan:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">az appservice plan create --name {APP_PLAN_NAME} --resource-group {GROUP_NAME} --is-linux<\/pre>\n<p><span style=\"font-weight: 400;\">Create the web app:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">az webapp create --resource-group {GROUP_NAME} --plan {APP_PLAN_NAME} --name {APP_NAME} --deployment-container-image-name directus\/directus:latest<\/pre>\n<p><span style=\"font-weight: 400;\">Configure Azure to use port 8055 for Directus:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">az webapp config appsettings set --resource-group {GROUP_NAME} --name {APP_NAME} --settings WEBSITES_PORT=8055<\/pre>\n<p><span style=\"font-weight: 400;\">Import the environment variables from your local project installation:\u00a0<\/span><\/p>\n<pre class=\"prettyprint\">az webapp config appsettings set --resource-group {GROUP_NAME} --name {APP_NAME} --settings DB_CLIENT=mssql\u00a0\r\n\r\nDB_HOST={DB_SERVER_NAME}.database.windows.net DB_PORT=1433\u00a0\r\n\r\nDB_DATABASE={DB_NAME} DB_USER={DB_ADMIN_USER} DB_PASSWORD={DB_ADMIN_PASSWORD} DB_OPTIONS__ENCRYPT=true KEY={KEY} SECRET={SECRET}<\/pre>\n<p><span style=\"font-weight: 400;\">(See your local .env file for the correct values to use above.)\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">You now have your Directus installation running on the web! You can access it directly on {APP_NAME}.azurewebsites.net. Try executing some of the requests from earlier to this new address!<\/span><\/p>\n<h2><span style=\"font-weight: 400;\">Summary\u00a0<\/span><\/h2>\n<p><span style=\"font-weight: 400;\">You have now created a production-ready installation of Directus on top of your own Azure SQL database. Explore more of Directus by adding more collections, fields, roles and permissions, and by taking a look at Insights, modifying files, and more.\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">If you&#8217;re looking for a one-click ready-to-go deployment of everything we went over in this post, check out <\/span><a href=\"https:\/\/docs.microsoft.com\/en-us\/samples\/azure-samples\/azure-sql-db-rest-graphql-directus\/azure-sql-db-rest-graphql-directus\/\"><span style=\"font-weight: 400;\">this article and GitHub Repo<\/span><\/a><span style=\"font-weight: 400;\"> to learn how to complete an end-to-end setup.<\/span><\/p>\n<hr \/>\n<p>Photo by\u00a0<strong><a href=\"https:\/\/www.pexels.com\/@nathansalt?utm_content=attributionCopyText&amp;utm_medium=referral&amp;utm_source=pexels\">Nathan Salt<\/a><\/strong>\u00a0from\u00a0<strong><a href=\"https:\/\/www.pexels.com\/photo\/photo-of-man-riding-red-motor-scooter-2549355\/?utm_content=attributionCopyText&amp;utm_medium=referral&amp;utm_source=pexels\">Pexels<\/a><\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Extremely performant and built entirely on Node.js, Directus is an open-source Data Platform that installs as a layer on top of your existing SQL database, so that you can you instantly get a dynamic API (REST and GraphQL) to your database<\/p>\n","protected":false},"author":24720,"featured_media":1119,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[409,504,431,410],"class_list":["post-1116","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-azure-sql","tag-api","tag-graphql","tag-node","tag-rest"],"acf":[],"blog_post_summary":"<p>Extremely performant and built entirely on Node.js, Directus is an open-source Data Platform that installs as a layer on top of your existing SQL database, so that you can you instantly get a dynamic API (REST and GraphQL) to your database<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/posts\/1116","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/users\/24720"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/comments?post=1116"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/posts\/1116\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/media\/1119"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/media?parent=1116"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/categories?post=1116"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sql\/wp-json\/wp\/v2\/tags?post=1116"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}