AWS Amplify Admin UI was announced just prior to AWS re:invent 2020, the killer feature for me was the ability to start building out the data persistence model for an application without needing access to an AWS Account. So in this blog post I will take you through how to add a data model and a persistence store to an existing React application and how you can go about testing it locally.
For those who have not come across AWS Amplify before it is a great way to start dipping your toe into the full stack cloud development experience if you have not already. It is an opinionated framework that makes assumptions on the developer's behalf, so less time on scaffolding boiler plate code and more time building features. Also, the Amplify documentation is (in my opinion) the best documentation you'll find for an AWS service. Don't take my word for it - see for yourself.
This is the first in a two part series, if your more of a visual learner then check out part 2 where I have included a video detailing all the steps I took for the demo.
What are we building?
For this blog we will work with an app that already has had the bones of the UI built in. The apps purpose is to collect information about shopping lists, allowing a user to Create Read Update and Delete items in a shopping list. Now with the existing UI done we want to start thinking about persisting the application's data. To do this we will use the Amplify Admin UI to model what the data objects will be, what fields and types they contain, which fields are optional and which are mandatory.
Getting Started
So lets go ahead and open the AdminUI sandbox.
From here we get to choose what we are building, either:
- Application Backend
- Hosting a Web Site
Ultimately, we want to build out an application backend for this application, so we choose the first option 'Create an app backend'. You will then be presented with the following options:
We can either start modelling the data layer, set up an auth layer or configure file storage for our application. In this case we are focusing on data, so lets choose 'Data >>'
Modelling our data
Next, we start to think about our data model, its relationships and how to test it locally. This can all be done when we select the 'Data' feature and then selecting the 'Blank Schema' option, as we want to start from scratch, finally hitting 'Create New Schema' to get going.
With the Admin UI data modelling feature we can do things like choose the names and types for my data. For individual types we can decide if they are simple types like 'String' or more complex scalar types like AWSDateTime. Along with model / field names and types we can also mark the fields as mandatory by ticking the 'isRequired' checkbox, or mark them as being a collection by ticking the 'is array' checkbox. Finally we can easily define relationships between model elements, currently I can define a 1:1, 1:M and M:M relationships inside the AdminUI.
The model we want to define is, a ShoppingList which can have 1:M ShoppingListItems -> so, modelling that in the AdminUI looks something like this.
For more in depth instructions on how to get started with data modelling, check out Amplify Docs
Next we can test this locally to see if it fits our understanding and the existing front-end code. Selecting 'Test this Locally' brings up a set of steps we need to perform to integrate this new model into the application.
Note - We can also share this model with other developers in the team as well as make it a template to base other models on. The model will exist in this sandbox until it is deployed into an AWS account, at which stage it will be locked down.
Adding Amplify to our app
The steps on how to build and test our newly created schema are nicely laid out for us as a series of steps in the AdminUI, so let's step through these
Step 1
Choose the type of App we are building - we can choose either a Web, IOS or Android platform and then make the appropriate framework/language selection based on our platform selection. For this example, we are choosing a Web platform with React as the framework.
Step 2 (Optional)
This step will contain the commands needed if you are creating an app from scratch. As we are using an existing frontend UI, we will skip this step.
Step 3
The next step contains the commands needed to install the Amplify CLI, which we then use to pull down the data model we have created in the AdminUI Sandbox. This 'amplify pull' command will also in our case generate the correct types that we can use to access our data model in our React code.
Step 4
This step shows us how to install the Amplify typescript library that we can use to interact with the types pulled down and generated in Step 3. It also shows us how to configure our application to start implementing Amplify libraries in our frontend code.
Step 5
Finally, this step shows how to build CRUD operations into our application by supplying code snippets for dataStore. Datastore is an Amplify category/feature that enables applications to be built with a client first programming model. The beauty of the datastore category is that once we deploy a backend for our app into an AWS account, the data persistence mechanisms we have defined in datastore will mean all application data will automatically be synced to all connected clients. This is due to the service that underpins datastore, AWS Appsync.
For a more in-depth view of what datastore can do -> check this out
So, for the ShoppingListItem model, if I want to persist items into our local datastore we would use the datastore API and code something like:
DataStore.save(new ShoppingListItems({"itemName": itemName})
The datastore API is pretty elegant, in that with this line of code we are storing the result in indexedDB in your local browser. But before we check to see if this is working, lets explore how we would code the other CRUD operations.
//READ
export async function getUserItems() {
return await DataStore.query(ShoppingListItems)
}
//CREATE
export async function addItem(itemName) {
return await DataStore.save(new ShoppingListItems({
"itemName": itemName
})
);
}
//DELETE
export async function deleteItem(itemId) {
const modelToDelete = await DataStore.query(ShoppingListItems, itemId);
return DataStore.delete(modelToDelete);
}
Testing Locally
So now we have modelled our data in AdminUI, installed the Amplify CLI, pulled down the required libraries and model schema from the AdminUI sandbox, generated types in typescript for our model AND changed our application to call the datastore API for these types. We have done a lot in a short time, the last thing we need to do is test it all works.
As mentioned before, when calling datastore API's we actually persist the data in IndexedDB in the browser, which makes it super easy to test. We can simply spin up the application, create some test data by executing the app's functionality. Then, if we want to make sure the data is persisting in the format expected, we can inspect it using the development tools of the browser and query indexedDB as shown below
Note - If, we are building an Android our IOS application, datastore would instead persist the data in SQLite database on the device as opposed to indexedDB in a browser.
Whats Next
If we are not happy with our model, we can go back to our sandbox and re-model our data again.
amplify pull --sandboxId
Running this command once more will retrieve any changes to our model and re-generate the types accordingly inside our codebase. This way we can quickly iterate on our model until it is fit for purpose.
When we are finally happy with the application and the data that it is persisting, we can move on to connecting our AWS account up and start to think about adding other features like datasync, authentication, content management and user management.
I will cover how this is done in a later blog.
Conclusion
As you can see Amplify AdminUI is a great way to start modeling and iterating on our datamodel that we want to use within our application. As there is no AWS account involved its very easy to just dive in and get started and the feedback cycle is really fast. This enables a faster application development cycle and and helps aid faster delivery of our application into the hands of real users.
So dont put it off any longer, dive in to the Amplify AdminUI and start building that next killer app.
In the next post I will describe how we take this application to the next phase of development by deploying it to an AWS account and adding more advanced features like auth and datasync/notifications. I'll also show you how you can delegate access to developers who dont have AWS accounts themselves.
Also, If there is specific content you want to see around this or other AWS topics, please get in touch.
Top comments (3)
Hi Derek, Lately I noticed an issue with the Admin UI. Once my data modeling is completed, I input some data into my tables & pulled it into my React project. But after some time my data won't show at all..! Not sure all the data is getting wiped out. however, when I ran the App Sync Query all my data is coming
Hi @penumatv - not sure I have witnessed that behaviour, however you do raise a great point that I failed to mention in the article. All issues for the AdminUI are in github.com/aws-amplify/amplify-adm..., so if your experiencing a problem, look here first.
Your issues sounds more related to datastore however so again I would refer to github.com/aws-amplify/amplify-js/... or whatever platform your are building for, for more help or to raise the problem with the team.. hope this helps
Thanks, Derek for the Github link. This time I will do it again from scratch and report in Github.