Forem: Camdyn Rasque

Understanding REST APIs - A Guide for the Impatient

Camdyn Rasque — Sat, 09 Nov 2024 00:41:56 +0000

REST (Representational State Transfer) APIs are the backbone of modern web development. This article will break down how to create and use modern REST APIs, what design decisions to take into consideration when making one, and the theory being the foundation of REST.

Practical Guide

This section dives into using REST APIs with HTTP covering endpoints, methods, requests, and responses. You'll find everything you need to start making API calls and applying REST in your projects.

How to Structure Your URIs

In general there are two main ways you can treat a URI:

As an action
As a resource

Consider the two following URIs:

https://example.com/getUserData?id=1 (action)
https://example.com/users/1 (resource)

Both examples show us retrieving user data of a user with an id of 1. The difference being that in the first example the route /getUserData is performing an action while in the second example the route /users/1 is the location of an asset, it does not indicate what action is being performed. We could say that this type of URI is acting as a noun (as it is a thing instead of an action i.e. a verb).

The REST pattern dictates that we strictly use URIs like the second example. We want our URIs to be nouns so that we can use HTTP Methods as our verbs to perform actions upon those nouns. For example, we can use the HTTP method GET to retrieve information about /users/1, but we could use PUT to update that corresponding user's information, or DELETE to delete the user entirely.

The last thing to note about URIs is that, as with the example above, when referencing an individual resource (e.g. a single user in this case) the URI should end with the unique identifier for that resource. When referencing all resources in a given category, the unique identifier should be omitted.

https://example.com/users/1 - References a particular user with an id of 1
https://example.com/users - References all users regardless of id

What Actions to Support

There are 4 main actions to support in REST, we use the acronym CRUD to remember them: Create, Read, Update, Delete. Each of these actions maps to an HTTP Method that we can use to perform that action. The mapping is as follows:

Action	HTTP Method
`Create`	POST
`Read`	GET
`Update`	PUT / PATCH
`Delete`	DELETE

All Action + URI Combinations to Support

Every REST API is really just (at a minimum) 5-6 routes. In our example, the base endpoint will be /users and we'll pretend to host it on https://example.com.

GET https://example.com/users
- Action: Return all user assets (each asset is one user)
- Request Body: Empty
- Response Body: List of user assets (as a JSON array)
GET https://example.com/users/[id] ([id] is a variable)
- Action: Returns just the singular requested user asset
- Request Body: Empty
- Response Body: Just the user asset with the matching id (as JSON)
POST https://example.com/users
- Action: Adds one user asset to the collection
- Request Body: All data needed to create the new user asset (no specific format required, JSON recommended)
- Response Body: The newly created asset that was inserted + a unique ID (as JSON)
PUT https://example.com/users/[id] ([id] is a variable)
- Action: Fully replaces just one existing user's data with the given data
- Request Body: All data needed to replace an existing user's data, whether or not it has changed (minus the id - no specific format required, JSON recommended)
- Response Body: The newly updated asset with the matching id (as JSON)
(Optional) PATCH https://example.com/users/[id] ([id] is a variable)
- Action: Partially replaces just one existing user's data with the given data
- Request Body: Only the data that needs updating (minus the id - no specific format required, JSON recommended)
- Response Body: The newly updated asset with the matching id (as JSON)
DELETE https://example.com/users/[id] ([id] is a variable)
- Action: Deletes just one record from the users table
- Request Body: None
- Response Body: None (just HTTP response code) OR The data from the asset that was just deleted with matching id (as JSON)

Design Considerations

Outside of what defines an endpoint as using the REST pattern or not, there are many things to take into consideration before you start building one. Is there a chance that you might want to update your endpoint in the future? Should your output give helpful hints to users? Is REST even the right pattern to use in your situation? Let's answer some of these questions.

Versioning Your Endpoint

It might be a good idea to start thinking about versioning of your API right from the start so that making changes is easier in the future. There are a few different methods for determining what API version your users are choosing to use:

URI Versioning
- The version numbers are incorporated into a URL path, usually at the base
- Examples:
- https://example.com/v1/users/1
- https://example.com/v2/users/1
Query Parameter
- The version number is appended as a query parameter in the API endpoint
- Examples:
- https://example.com/users/1?apiVersion=1
- https://example.com/users/1?apiVersion=2
Header based
- The version number is a specific and unique header field
- Examples (Request Headers):
- x-api-version: 1
- x-api-version: 2
Content Negotiation
- The version is determined based on the representational state or media type.
- In the example below, the server code would know that firstName is for the first version and that it was changed to givenName in the next version.
- Examples (Request Body):
- { firstName: 'Henry' }
- { givenName: 'Henry' }

Mocking a Quick REST API

Sometimes playing around with one is the best tool to learn how they work. One of my favorite libraries to demo REST is json-server. Setting it up is pretty simple - just a few steps required.

Install JSON Server

npm install json-server

Create a simple data store

{
  "users": [
    { "id": "1", "username": "gorwell", "email": "gorwell@gmail.com" },
    { "id": "2", "username": "cdickens", "email": "cdickens@gmail.com" },
    { "id": "3", "username": "jausten", "email": "jausten@gmail.com" },
    { "id": "4", "username": "vwoolf", "email": "vwoolf@gmail.com" },
    { "id": "5", "username": "sking", "email": "sking@gmail.com" }
  ]
}

Start up the server

npx json-server db.json

Make an HTTP request against your local server

curl -X GET http://localhost:3000/users/1

An Easy CRUD Data Grid

A fully functioning REST endpoint can be hooked up to a data grid easily with ZingGrid, just point the base REST URI at the <zing-grid> element's src attribute like below

<zing-grid
  src="http://localhost:3000/users"
  editor-controls
></zing-grid>

Final Thoughts

REST APIs come in many shapes and sizes across the web, each tailored to meet specific needs. By structuring URIs thoughtfully, choosing the right actions, and keeping versioning in mind, you can create a straightforward, flexible API that developers will find a pleasure to work with. With these foundational steps, even a quick prototype can evolve into a robust, reliable API that stands the test of time.

How to Add an Excel-like Table to Your Astro Site (the Easy Way)

Camdyn Rasque — Tue, 22 Oct 2024 23:02:23 +0000

Cross post from my article on the Zing blog.

The philosophy of Astro is one of performance, flexibility, and customization. A web framework that prides itself on rendering as much as it can on the server first, allowing you to choose where your content lives, and giving you as many handles as possible to customize it how you like. The datagrid library you go with should be the same.

Initial Setup - Installing Astro

First things first, we have to setup a basic app—we'll do that by following the prompts in the following command

npm create astro@latest

Initial Setup - Including ZingGrid Library

The library itself should be included as a script in the front-end (preferably deferred using defer) for a few reasons:

It needs to be included exactly once
While the library itself is small for the sheet volume of features it packs (~259kb compressed), it is too big to be inlined in the HTML and maintain RAIL
- Quick side note: the is:inline directive in Astro really means to opt the script out of any bundling and processing, not that the script will actually be fetched and swapped in place during the build process
A direct integration is not needed as ZingGrid was already build with similar philosophy to Astro in mind

`src/layouts/Layout.astro`

<!-- ... --->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="description" content="Astro description">
  <meta name="viewport" content="width=device-width">
  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  <meta name="generator" content={Astro.generator} />
  <title>{title}</title>
  <!-- ZingGrid Library -->
  <script is:inline defer src="/zinggrid.min.js"></script>
</head>
<body></body>
</html>

Creating the Activity Tracker Grid

We'll start with the simplest grid we can make and build up from there. First things first, we create a ActivityGrid.astro component in our src/components directory and add the following code.

We'll be passing our data to this component, so we create a prop for that, and we hand it to <zing-grid> using the data attribute.

`src/components/ActivityGrid.astro`

---
const { data } = Astro.props;
---

<zing-grid data={data}></zing-grid>

Over in our index.astro page in src/pages, we need to add our grid to the page. To do this we'll first need to import the component in our frontmatter (fenced off by ---), and we'll need to pull in our sample JSON as well. Now the only thing we have to be careful of is that we stringify the JSON as it will be passed into <zing-grid> as an attribute.

`src/pages/index.astro`

---
import Layout from '../layouts/Layout.astro';
import ActivityGrid from '../components/ActivityGrid.astro';

import activityData from '../data/activities.json';
const activityDataStr = JSON.stringify(currencyData);
---

<Layout title="ZingGrid + Astro">
  <header> <!-- ... --> </header>
  <main>
    <ActivityGrid data={activityDataStr} />
  </main>
</Layout>

When we load up the page, we'll see a grid that looks like this. Nothing fancy yet, but surprisingly easy to get something going.

Adding User Controls and a Caption

To enhance our grid we'll start by configuring our element. With 100+ attributes to choose from the element has a ton of configuration available to it, but I'll pick out a few I think will be useful to us here:

layout : Determines whether or not the grid is shown in row or card mode
layout-controls : Allow / prevent users from changing the layout mode
sort : Add controls to sort each column
pager : Paginates the grid instead of leaving it as one long list
page-sizer : The number of rows for each page

We'll also add a <zg-caption> inside of our <zing-grid> so we can give our grid a title

---
const { data } = Astro.props;
---

<zing-grid
  data={data}
  layout="row"
  layout-controls="disabled"
  sort
  pager
  page-size="6"
>
  <zg-caption>💃🏼 Activity Tracker</zg-caption>
</zing-grid>

Formatting the Columns

Having a Distance column without any units makes it a bit hard to read. Luckily ZingGrid allows us to create templates for our columns. We can access the values from our row entry using the index object inside of [[double bracket]] notation. Below is a sample of what our data looks like for reference, the "distance" key is what we're pulling in when we write [[index.distance]] in the template.

`src/data/activities.json`

[
  {
    "activityType": "Outdoor Bike",
    "city": "Tempe",
    "date": "10/17/24",
    "distance": "48.27",
    "elapsedTime": "03:26:35",
    "movingTime": "01:53:15",
    "state": "Arizona"
  },
  /* ... */
]

`src/data/ActivityGrid.astro`

<zing-grid
  data={data}
  layout="row"
  layout-controls="disabled"
  sort
  pager
  page-size="6"
>
  <zg-caption>💃🏼 Activity Tracker</zg-caption>
  <zg-colgroup>
    <zg-column index='date'></zg-column>
    <zg-column index='activityType'></zg-column>
    <zg-column index='city'></zg-column>
    <zg-column index='state'></zg-column>
    <zg-column index='distance'>[[index.distance]] mi</zg-column>
    <zg-column index='elapsedTime'></zg-column>
    <zg-column index='movingTime'></zg-column>
  </zg-colgroup>
</zing-grid>

And the result is the mi unit being added to each Distance value just as in our template

Styling the Grid with CSS Vars and Open Props

ZingGrid is built with modern native web components for performance and resiliency, but as a side effect of that a lot of the components exist inside Shadow DOMs. Still wanting to allow users to style any part they desire, hundreds of CSS Variables were created to pierce these shadows. Below we show how they can be used in conjunction Open Props for added flexibility.

<style>
  zing-grid {
    --zg-body-color: var(--gray-8);
    --zg-caption-background: white;
    --zg-caption-border-bottom: 1px solid var(--gray-3);
    --zg-caption-color: var(--gray-8);
  }
</style>

Custom Cell Render Functions

To add some extra life to our grid it would be nice to be able to dynamically add an emoji in front of each activity. To do this, we'll create a function called activityRender on the window object (so it's accessible to ZingGrid) and add specify the function name the renderer attribute for the <zg-column> we want to apply it to. Inside this function we'll have the record text passed into us that we can then modify before it gets inserted into the cell.

<zing-grid>
  <!-- ... -->
  <zg-colgroup>
    <!-- ... -->
    <zg-column index='activityType' renderer='activityRender'></zg-column>
    <!-- ... -->
</zing-grid>

<script>
  window.activityRender = function (record) {
    let sportEmoji = '';
    if (record === 'Outdoor Bike') sportEmoji = '🚴‍♂️';
    else if (record === 'Sport') sportEmoji = '⛳️';
    else if (record === 'Run') sportEmoji = '🏃‍♂️';
    return `${sportEmoji} <strong>${record}</strong>`;
  };
</script>

Dynamically Adding Classes to Rows

And then finally to color each row based on the activity type, we can use the row-class attribute to pass a function that will dynamically add a class to each row.

<zing-grid
  row-class="activityClassRender"  
>
  <!-- ... -->
</zing-grid>

<script>
  // ...
  window.activityClassRender = function(record, rowIndex, rowDOMRef) {
    let rowCQlass = '';
    let activity = record.activityType;
    if (activity === 'Outdoor Bike') rowClass = 'outdoor-bike';
    else if (activity === 'Sport') rowClass = 'sport';
    else if (activity === 'Run') rowClass = 'run';
    return rowClass;
  }
</script>

We'll then need to create those classes in a global CSS style block as the <zg-row>s are created dynamically on the front-end and thus do not get tagged with the usual style scoping attributes that Astro adds at build time.

<style is:global>
  zing-grid zg-row.outdoor-bike {
    --zg-row-color: var(--blue-8);
  }

  zing-grid zg-row.sport {
    --zg-row-color: var(--teal-8);
  }

  zing-grid zg-row.run {
    --zg-row-color: var(--red-8);
  }
</style>

Et Voilà! 😄 We have a dynamically styled and formatted ZingGrid inside of Astro

Final Thoughts

With just a little configuration and very little code we were able to construct a robust and dynamic datagrid that fit with our Astro site. We've only scratched the surface of what ZingGrid can do in this article, so there will be a part 2 later on to show what the library can truly do, so watch out for that here if you're interested.

Connecting ZingGrid to Supabase: Add a Backend in Minutes

Camdyn Rasque — Fri, 13 Sep 2024 00:03:45 +0000

Cross post from my article on the Zing blog.

Supabase is an open source Firebase alternative. There are a variety of services they offer, but for the purposes of this article, we'll be diving into how it can act as a simple backend for our grids.

Initial Setup

There are a few steps we need to run through on the Supabase side of things before we can start configuring our grids.

1. Account Creation

We first need to create the Supabase account that we will be connecting to. You can sign up for Supabase using this link. Once your account has been created and email confirmed, continue to the next step.

2. Create Your First Project

Go ahead and head over to the dashboard page and create a new project. Make sure to note down the project name and database password.

3. Note Down Project Info

It is at this point you should see your Project URL and your API Key. We will need to give both of these to ZingGrid in our code later so make sure to store them in a secure local file.

4. Create Your First Table

From the side bar click the Table Editor section. From here we can create our first table

First step is to give our table a name, here I'll use demoTable

Then we can edit the columns, I'll have two columns for this example. One for first names and one for last names.

5. Add Some Sample Data

6. Update Security Settings

We'll temporarily disable Row Level Security so we can easily read and write from our table for the purpose of this demo. In production we'll want to set up proper roles with authentication.

⚠️ NOTE: This settings change is just for the purpose of this demo, this is not meant for production

Supabase Adapter - REST API

ZingGrid supports both ways of interacting with Supabase - via the REST API and via the client script. We'll first go over using the REST API.

Using the initial demo code below, make sure to replace the following:

***link*** - The Project URL that you noted down earlier
***tableName*** - The name of the Supabase table you just created
***apiKey*** - The Supabase API Key you noted down earlier

<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <script src="/lib/zinggrid.js"></script>
  <title>Supabase</title>
</head>
<body>
  <zing-grid
    page-size="5"
    sort
    pager
    title="Supabase"
    editor-controls
    editor-disabled-fields="id"
    src="https://***link***.supabase.co/rest/v1/***tableName***"
  >
    <zg-data adapter="supabase">
      <zg-param
        name="headers"
        value='
          {
            "Authorization": "Bearer ***apiKey***",
            "apikey": "***apiKey***"
          }'
        ></zg-param>
    </zg-data>
  </zing-grid>
</body>
</html>

When viewing that page in the browser, you should start to see the initial data we populated come through!

SupabaseJS Adapter - Client Script

If your app happens to use the Supabase JavaScript Client Library (which you can read more about on their docs site), you are able to store your Supabase credentials outside of your markup making it much more flexible.

Amending the previous example, we first create a Superbase client object (more on that in their docs)

const supabaseUrl = 'https://***link***.supabase.co/';
const supabaseKey = '***apiKey***';
const supabaseClient = supabase.createClient(supabaseUrl, supabaseKey);

and then register that client with ZingGrid

ZingGrid.registerClient(supabaseClient);

Finally we set the adapter attribute on zg-data to supabaseJS and we have the following

<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Supabase</title>
  <!-- ZingGrid -->
  <script src="https://cdn.zinggrid.com/zinggrid.min.js"></script>
  <!-- Supabase Client Library -->
  <script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>
</head>
<body>
  <script>
    const supabaseUrl = 'https://***link***.supabase.co/';
    const supabaseKey = '***apiKey***';
    const supabaseClient = supabase.createClient(supabaseUrl, supabaseKey);
    ZingGrid.registerClient(supabaseClient);
  </script>
  <zing-grid
    page-size="5"
    sort
    pager
    title="SupabaseJS"
    editor-controls
    editor-disabled-fields="id"
  >
    <zg-data adapter="supabaseJS">
      <zg-param name="dataTable" value="***tableName***"></zg-param>
    </zg-data>
  </zing-grid>
</body>
</html>

Working the same as before