DEV Community: Azamah Jr

Appwrite storage service

Azamah Jr — Thu, 28 Oct 2021 19:55:04 +0000

Appwrite is an open-source, self-hosted Backend-as-a-Service which provides a suite of SDKs and APIs to facilitate development on any platform. In this article we are going to look at Appwrites' Storage service and API which lets you manage your project files

Appwrites storage service grants read and write permissions to manage access to every file in storage, this lets authenticated users upload, download, view and query and manage all project files.

Storage can be managed and manipulated in two ways;

Using Appwrites console
Using Appwrites storage API, which provides various endpoints to manipulate files in storage

To demonstrate Appwrites storage service, in this article we will be utilizing Appwrites storage API to manage and manipulate images files in our demo react app

Prerequisites

This article assumes you have appwrite installed, if you don't heres an article to get you started
Basic knowledge of javascript and react

About the demo app

The front end of the app has been pre built, and in this article we would focus only on implementing functionality in the app using Appwrite as our backend and Appwrites storage API. The following functionalities;

Upload an image to storage
Delete an image
Get and Display all images we currently have stored
Download stored images
For this demo we want to provide authentication so users can have permissions to read and write to storage , but we want to keep it simple here so we are going to implement an Anonymous login using Appwrites createAnonymousSession() method , where users can create an account without providing information such as an email address, username or password.

Implementing each of the above functionalities we will be utilizing endpoints from the storage API, and as such we will gain hands on experience in utlizing the storage API in a real word scenarios.

Note: We will not cover how to build the demo app with react in this video. However i'll provide links to the projects starter files, which you can clone from github and follow along to implement functionality with Appwrite

Setup

Clone the project starter files Here to code along

Once you've cloned the project repository, navigate to the project folder and run the following command in the projects root to install the projects dependencies

npm install

Create new Appwrite project

In Appwrites console, create a new project and name it purp-flower.

In the project we just created, click the add platform button and add a web platform so we can initialize the web SDK and interact with Appwrite services in our react app

Configuring Appwrite

In the project root, run the following command to add Appwrite to the project

npm install appwrite --save

First up, lets import the Appwrite module, navigate to src/appwrite/appwrite.congfig.js and enter the following code

// Import the Appwrite module
import { Appwrite } from "appwrite";

The next step is to initialize our web SDK with our project ID and our Appwrite endpoint, which can both be found in the project settings page in the Appwrite console

// Init your Web SDK
const appwrite = new Appwrite();

appwrite
    .setEndpoint('http://localhost/v1') // Your Appwrite Endpoint
    .setProject('455x34dfkj') // Your project ID
;

export const storage = appwrite.storage
export const account = appwrite.account

Ok lets begin implementing our apps functionality

Uploading images & Anonymous login

Before a user can be permitted to upload an image to storage, they have to be authenticated, as earlier mentioned we will implement anonymous login to authenticate users without requiring usernames and passwords

Uploading a file to storage using the web SDK requires the storage.createFile() method. This method requires three parameters: a file, an array of strings to define the read permissions, and an array of strings to define write permissions.

In the src/app.js file in the project, lets create an uploadImage() function, copy the code below.

// 1. Upload images to appwrite
  const uploadImage = async (e) => {
    e.preventDefault();

    try {
      // Checks if user is logged in current session
      const user = await account.getSession("current");

      for (let i = 0; i < image.length; i++) {

        if (user) {
          // Upload image
          await storage.createFile(image[i], ["*"], ["*"]);
          console.log('Image uploaded successfully!');
          window.location.reload(); // Reloads window on upload
        } else {
          // Create anonymous user
          await account.createAnonymousSession();
          await storage.createFile(image[i], ["*"], ["*"]);
          console.log('New user was created ');
          window.location.reload();
        }
      }

    } catch (error) {
      console.log(`${error.message}`);
    }
  };

Lets take a closer look at the storage.createFile()method

storage.createFile(image[i], ["*"], ["*"])

The first parameter of this method is an image within an array of images, the second parameter defines the read parameters, setting the array of strings to and asterisks, grants read access to all users no matter their role. We can restrict this access to users of certain roles. The third parameter defines the write permissions, and like the read permission, all users of the application have been granted write access

Next we get the currently logged in user, if there exist a logged in user, we upload the image file to storage and if the user isn't authenticated and logged in, we call the account.createAnonymousSession which creates and logs in an anonymous user. Once thats done, we then upload the image.

Now go ahead and upload a couple of images to storage using the demo app

We can check to see if our images were uploaded to storage using Appwrites console, and as you can see below the images were uploaded

Getting a list of all images in storage

To get a list of all images we have in storage we require the use of the storage.listFiles() method, once we get the list we will store it in an imageList state. Copy the code below to implement the getAllStoredImg()function

const getAllStoredImg = async () => {
    const images = await storage.listFiles();
    console.log(images)
    setImageList(images.files);

};

We would want our application to get the list of all images in storage each time the app reloads, the code below implements that

 useEffect(() => {
    getAllStoredImg();
  }, []);

Now we have a list of all images currently in storage, next lets display the images, we need to use the storage.getFilePreview(imgID) method, and would take an image ID as parameter.

As we probably have a lot of images stored, we therefore loop through the imageList state to get each image ID from the list and parse that as a parameter to the storage.getFilePreview()method to preview the image, how this was done with react is beyond the scope of this article

At this point the demo app should look like this:

As you can see, we are getting and displaying all the images we had stored. Next lets implement the delete and download features

Delete an image

Deleting an image requires the use of storage.deleteFile()method, as a parameter we pass in the image Id of the image in storage which we want deleted

// 2. Delete an image
   const deleteImage = async (e, imgId) => {
    e.preventDefault();

    try {
      await storage.deleteFile(imgId);
      window.location.reload();
      console.log("Image Deleted Successfully");
    } catch (error) {
      console.log(`${error.message}`);
    }
  };

Download an image

To download an image from storage we require the use of storage.getFileDownload(imgID)method, this method takes the image ID as a parameter

const downloadImage = (e, imgId) => {
    e.preventDefault();

    try {
      const downloadLink = storage.getFileDownload(imgId);
      window.open(downloadLink.href);
    } catch (error) {
      console.log(`${error.message}`);
    }
 };

Conclusions

We've implemented all the functionalities of our demo app, i am glad you made it this far. if you have any questions let me know down in the comments

Here are some links if you want to learn more on the Appwrite features which were implemented in this article;

Thanks for reading, thats all for now ✌️

RESTful APIs in 4 minutes

Azamah Jr — Mon, 06 Sep 2021 22:37:44 +0000

APIs, What Are They🤔?

API stands for Application programming interface, it is an intermediary between two or more applications or services that provide a set of rules and definitions that define how the applications or services can connect and communicate with each other, all while abstracting how each application, involved in the communication is implemented.

This communication entails sharing data and business functionalities between applications via HTTP (Hypertext Transfer Protocol).

Web applications use APIs to connect client-facing, frontends to the backends functionality and data.

Why Use APIs🤔

APIs make it easier for apps running in different environments or written in different languages to share information, this can simplify app development, reduce development time and cost.

Ok, let's say an application you are developing requires an authentication and authorization feature. Rather than delegating time and resources in building and maintaining a login system, the functionality provided by APIs of services such as Auth0 can be leveraged to authenticate/authorize and login users into the application.

So What Are RESTful APIs?🤔

Well REST stands for Representational State Transfer Architectural Style. A RESTful API is an API that conforms to the 6 guiding constraints of REST, such APIs could also be referred to as simply REST APIs

These 6 constraints of REST are;

Client-server architecture:

REST architecture is composed of clients, servers, and resources, and it handles requests through HTTP messages, but the clients and servers must be completely independent of each other. The only information the client knows is the URI (Uniform Resource Identifier) of the requested resource. The server provides this requested resource by sending it through an HTTP response. The server shouldn't be able to modify the client application other than providing a requested resource.

Statelessness:

Session Data is sent to the server from the client in such a way that each data packet can be understood in isolation. The server does not retain session state or data, instead, session states or data are held with the client

Cacheability:

Clients can cache server responses, caching can eliminate the need for some client-server interactions which further improves performance

Layered system:

Clients and servers may not necessarily be connected directly with each other. They may be mediated by additional layers such as security layers, load balancers, and intermediate servers. These layers could offer additional features like load balancing, shared caches, and security.

Code on demand (optional):

Servers can extend the functionality of a client by transferring executable code.

Uniform Interface:

All API requests for the same resource should look the same. The REST API should ensure that the same piece of data belongs to only one URI. Resources shouldn’t be too large but should contain every piece of information that the client might need

If an API violates any of the guiding constraints, it can not be considered a RESTful API

How RESTful APIs work👩‍🏭

Let's take an example. We want to build a simple application that connects to a server and provides the functionality of creating, reading, updating, and deleting resources (also known as CRUD) within the database

A RESTful API is built and used to connect and provide communication between our client-facing front end to the back end server and database.

When users of our application make client requests on the front end to retrieve a resource from within the database, the RESTful API is called, it makes a GET request to retrieve the resource,
To create a resource within the database the RESTful API makes a POST request.
To update a resource the RESTful API makes a PATCH request
To delete a resource from within the database, the RESTful API makes a DELETE request to the Server

The resource can be delivered to the client in a variety of formats including HTML, plain text, or Javascript object notation (JSON).

All HTTP methods can be used in RESTful API calls, we've seen the GET, POST, PATCH, and DELETE methods above. To learn more or have a refresher on HTTP, HTTP methods, and status codes as well as the Request-Response cycle check out this article.

Final thoughts

Understanding the concepts of HTTP is fundamental to building and working with RESTful APIs, if you haven't come across this before, I suggest you take some time to read this article to grasp the foundational concepts. In a later article, we will be building a RESTful API using ExpressJs and MongoDB.

I really hope that you enjoyed reading this article and learned something from it. If you have any questions let me know in the comments. I am passionate about sharing knowledge and helping others reach their goals, let's connect on Twitter. That's all for now✌️

HTTP Simplified

Azamah Jr — Fri, 03 Sep 2021 03:19:34 +0000

If you have an interest in Web development and building APIs, understanding the concepts of HTTP is vital.

In this article you are going to learn the following:

What HTTP is, and its characteristics
A brief history of HTTP versions
What Sessions are and their usage
The Request-Response cycle
HTTP Request and Response messages
HTTP methods and their operations
HTTP Status codes, their meanings, and what operations they perform

🤔What is HTTP?

HyperText Transfer Protocol (HTTP) is a stateless, connection-less, request-response protocol that consists of rules which define communications between clients and servers connected over an established Transmission Control Protocol (TCP) connection

Once there is an established connection between the client and the server, HTTP defines rules for transferring data such as images, text, and other multimedia between the client and the server

Before delving any further, let's define some basic terminologies which will be mentioned in the article.

Clients: The client is a web browser, search engine, or robot. The client sends the request message to the server
Servers: A web server that receives and responds to the request message sent by the clients, by sending a response message back to the client
User: The individual who enters a URI into the browser or request for specific resource within an application
URI( Uniform Resource Identifier): it is used to identify a given unique resource on the web

📜 History of HTTP

HTTP/1.0: It was the original HTTP. It opened a new TCP connection for each HTTP request-response exchange, this approach is less efficient when multiple requests are sent in succession, hence the need to address this flaw in later versions
HTTP/1.1: To mitigate the flaws of HTTP/1.0, pipelining was implemented which allowed multiple HTTP request-response exchanges over a single TCP connection
HTTP/2 goes a step further by multiplexing messages within frames over a single open TCP connection
- HTTP/2 messages a not human-readable and are embedded into frames which allows optimizations like compressions of HTTP headers and multiplexing.

Characteristics of HTTP

HTTP is stateless: There's no link between any two or more HTTP requests messages being successively sent out on the same TCP connection, this means from the server's perspective each HTTP request message is considered isolated and unique
HTTP is not connection-based: Before a client and server can exchange requests and responses there must be an established connection between the client and server, but HTTP is not connection-based, hence it relies on the TCP transport layer which is a connection-based protocol, to establish a secure connection between the client and the server
Once the server receives the HTTP request messages sent by the client on an opened TCP connection, the server analyzes and sends an HTTP response message to the client, after which the TCP connection is closed.

Although HTTP itself is stateless, there's a need to share state between multiple HTTP requests. HTTP cookies make it possible for the use of stateful sessions.

HTTP cookies are added to the header of each HTTP request allowing session creations on each HTTP request, doing this makes it possible to share state between multiple HTTP requests.

🤔What are Sessions

A session is temporal storage on the server, each session consists of the session data and the session ID which identifies a specific session. The session data is stored on the server while the session ID is stored in the client(web browser) using HTTP cookies. To identify a specific session, the session ID is sent back to the server using HTTP cookies

Characteristics of Sessions

Sessions are unique for each user. So if there are 4 users who make a request to the server, there will be 4 sessions created on the server.
During the request processing of each user, the user's sessions are available to all web pages on the application

Sessions usage examples

Sessions can be used to protect certain pages and routes so that only specific users can access them, we can keep track of the users when they log in, by storing their user's IDs in a session
Sessions can be used to keep track of a users' log status. So we can restrict access to protected resources and routes, to being available to logged-in users only. When a user logs in, their JSON Web Token(JWT) is stored in a session, and with subsequent user requests to a resource, it can be checked to see if the user is logged in

🔂The HTTP process

To understand the HTTP process, let's ask ourselves, what actually happens each time a user types a URL into a browser in order to open a new webpage. Well the most simple answer is;

The client which in this case is our browser, sends a request to the server in which the web page is located
The server then sends back a response containing the requested webpage to the client.

This process is called the Request-Response cycle.
Let's take it one step further.

Let's say we want to access the explore page on hashnode.com by entering the following URL into the browser

The URL is made up of;

Protocol: It is the protocol to be used on the connection, it could be HTTP or HTTPS, in this case, it is HTTPS which is the secure version of HTTP.
Resource: the resource which we want to access, in this case, it is the explore page
Domain name: In this case it's hashnode.com, we have to note that the domain name here is not actually the real address of the server that we are trying to access, rather it's just a nice and easy to remember representation of the actual address. So the client needs to convert the domain name to the actual address of the server, through the process of DNS( Domain Name Servers ) Lookup. The actual address of the domain name got from the DNS Lookup is;

This process of DNS Lookup only occurs when the HTTP request is made.

When a client initiates an HTTP request to the server, it performs the following steps;

It establishes a TCP connection between the client and server: the TCP connection is used to send requests and receive responses
Once the TCP connection has been established, the client sends an HTTP request message to the server
After interpreting an HTTP request message the server sends an HTTP response message to the client
Once the server has responded to the client's request, the TCP connection is closed

This process is illustrated below.

📝 HTTP messages

There are two types of HTTP messages;

HTTP Request messages sent by the client to the server
HTTP Response messages sent from the server to the client each of these messages has a format in which they are generated

HTTP Request Message

The request message consists of the following;

The HTTP method: these methods are usually a verb like 'GET' or 'POST' that defines the operation applied by the client to the resource, in this case, the HTTP method is GET note HTTP methods are case sensitive.
The Request-URI: identifies the resource upon which the HTTP method is applied. The exact resource is determined using the Request-URI and the Host header field
The HTTP protocol version: In this case the version is HTTP/1.1
Request headers: Conveys additional information about the request and about the client itself to the servers, in this case, we have the following request headers;
- Host: It specifies the internet port(IP) address and port number of the server where the requested resource is stored, an IP address without a trailing port defaults to port number 80 for HTTP requests and 443 for HTTPS requests. Note without specifying the Host header field, the request will return an error
- Accept-Language: Specifies which language the client is able to understand, in this case, the language is 'en' for English, other values could be 'fr' for French
Body: An optional field that contains the information being sent to the server for storage, mainly used when using HTTP methods like POST, PATCH

HTTP Response Message

The response message consists of the following;

The HTTP protocol version: In this case the version is HTTP/1.1
Status code: in this case, is 200
Response headers: Conveys additional information about the response and about the server itself to the client, in this case, we have the following request headers;
- Accept-Ranges: It is used by the server to show its support for partial requests
- Server: Describes the software used by the origin by the origin server that handled the request
- Content-type: This header field indicates the resource content type
- E-Tag: it identifies the specific resource version
Body: An optional field that contains fetched information being sent to the client from the server, mainly used when using HTTP methods like GET.

HTTP Methods

HTTP uses methods to define the operation to be applied to the resource identified by the Request-URI. These methods are usually verbs, with the most widely used methods being POST, GET, PATCH, and DELETE. Each of these HTTP methods returns a success or failure upon completion of their operations, using status codes to represent success or a failure.

GET: This method retrieves the resource specified in the request-URI. If successful the resource is returned as an entity in the response message along with the status code 200 (Success).
POST: This method request that the server accepts the data or entity enclosed in the Request body, if successful the server responds by sending a response message containing the status code 201 (Created), along with the location of the posted entity or data.
PUT: This method request that the enclosed data or entity in the Request body be used to modify the request identified by the Request-URI.
DELETE: This method request that the enclosed data or entity in the request be stored under the supplied Request-URI.

📱 HTTP Status Codes

The status codes are used by the client to determine if the HTTP request sent to the server, along with the specified operation was a success or a failure, remember the operation is specified by using the HTTP method.
The status code is a 3 digit result code, with the first digit defining the class of the code.

1xx (Informational): This class of status codes consists of informational responses indicating that a client should continue with a request. Examples of status codes belonging to this class;
- 100 Continue: The client should continue with their request
- 101 Switching protocols: The server is willing to comply with the request to change the application protocol being used in the connection, this request is made using the Upgrade message header field
2XX (Success): This class of status codes indicates that the request made by the client was successfully received, understood, and accepted by the server. Examples of status codes belonging to this class include the following;
- 200 Ok: The request succeeded, the information returned with the response is dependent on the HTTP method used in the request.
  - GET: the requested resource is sent in the response
  - POST: A description of the action is sent in the response
- 201 Created: The request has succeeded and a new resource has been created
- 202 Accepted: The request has been accepted but not yet processed by the server
3XX (Redirection): This class of status codes indicates that further action needs to be taken by the user to complete the request, examples of status codes belonging to this class;
- 301 Moved permanently: The requested resource has been moved permanently to a new URI, the permanent URI is given in the Location header field in the response
- 304 Not modified: A successful get request is made, but the client does not modify the resource
4XX (Client Error): This class of status code indicates that the client has erred. Examples of status codes belonging to this class;
- 400 Bad requests: The request could not be understood by the server
- 401 Unauthorized: The request requires user authentication
- 404 Not found: The server can not find any resource matching the resource-URI
5XX (Server Error): This class of status code indicates that the server has erred. Examples of status codes belonging to this class;
- 500 Internal error: The server encountered an unexpected condition with prevented it from fulfilling the request
- 503 Service unavailable: The server is unable to handle the request due to a temporal condition such as server maintenance or temporal overloading

You can read a lot more about status codes here

Conclusion

I hope you found this article useful and helpful, if you have any questions let me know in the comments. In a later article, we are going to learn how to implement and use these concepts in building a Rest API. That's it for now 👋