DEV Community: 99darshan

Build Interactive Maps in Next.js using Google Maps API

99darshan — Fri, 13 Jan 2023 11:33:50 +0000

This tutorial will demonstrate how to use google Maps API and Google Places API to build interactive maps in Next.js.

Demo

Here is a demo of what we will be building by the end of this tutorial.

Project Setup

Let’s scaffold a new Next.js app using create-next-app.

npx create-next-app@latest --ts

We will be using a package called @react-google-maps/api, which provides simple bindings to Google Maps Javascript API V3. This package lets us use google maps specific react components and hooks in our app.

npm install @react-google-maps/api

Similarly, in order to interact with Google Maps Places API, we’ll be using another package called use-places-autocomplete.

npm install use-places-autocomplete

Create Google Cloud API Key

Let's create a new key for our app from the Google Cloud Console Credentials.

Since we will be creating a client facing application, the api key would be exposed in the browser. So it’s a good idea to add some restrictions to the API Key. For example, in the screenshot below, we are specifying that only the requests originating from yourdomain.com are considered valid requests.

Also, our application only require the Maps Javascript API , Places API and Geocoding API, we’ve enabled only these APIs.

Before we could associate any of the google APIs to the key, we may have to first enable those API from Enabled APIs & Services tab

Rendering Map

In order to render the Map, we’d have to load the google Maps Script into our application.

Let’s use the useLoadScript hook provided by @react-google-maps/api package to lazy load the Google Maps Script.

useLoadScript expects a API Key, let’s use the key we generated from the Google Cloud Console in the previous step and access it using the next.js environment variable.

In addition to the API Key, useLoadScript hook accepts an optional libraries parameter where we could specify the array of additional google maps libraries such as drawing, geometry, places, etc.

The useLoadScript hook returns a isLoaded property which can be used to show a Loading component until the script is loaded successfully.

// pages/index.tsx

import { useLoadScript } from '@react-google-maps/api';
import type { NextPage } from 'next';
import styles from '../styles/Home.module.css';

const Home: NextPage = () => {
  const libraries = useMemo(() => ['places'], []);

  const { isLoaded } = useLoadScript({
    googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_KEY as string,
    libraries: libraries as any,
  });

  if (!isLoaded) {
    return <p>Loading...</p>;
  }

  return <div className={styles.container}>Map Script Loaded...</div>;
};

export default Home;

Once the script is loaded, we can use GoogleMap component to load the actual map. GoogleMap component requires a center prop which defines the latitude and longitude of the center of the map.

We can define other properties such as zoom, mapContainerStyle, etc. Additionally, GoogleMap also accepts MapOptions, mapTypeId props and other event listeners for map load and click events e.g. onLoad, onClick, onDrag , etc.

// pages/index.tsx

import { useLoadScript, GoogleMap } from '@react-google-maps/api';
import type { NextPage } from 'next';
import { useMemo } from 'react';
import styles from '../styles/Home.module.css';

const Home: NextPage = () => {
  const libraries = useMemo(() => ['places'], []);
  const mapCenter = useMemo(
    () => ({ lat: 27.672932021393862, lng: 85.31184012689732 }),
    []
  );

  const mapOptions = useMemo<google.maps.MapOptions>(
    () => ({
      disableDefaultUI: true,
      clickableIcons: true,
      scrollwheel: false,
    }),
    []
  );

  const { isLoaded } = useLoadScript({
    googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_KEY as string,
    libraries: libraries as any,
  });

  if (!isLoaded) {
    return <p>Loading...</p>;
  }

  return (
    <div className={styles.homeWrapper}>
      <div className={styles.sidebar}>
        <p>This is Sidebar...</p>
      </div>
      <GoogleMap
        options={mapOptions}
        zoom={14}
        center={mapCenter}
        mapTypeId={google.maps.MapTypeId.ROADMAP}
        mapContainerStyle={{ width: '800px', height: '800px' }}
        onLoad={() => console.log('Map Component Loaded...')}
      />
    </div>
  );
};

export default Home;

Drawing Over the Map

We can draw Markers, Rectangle, Circle, Polygon, etc. over the rendered map by passing the corresponding components as a child to GoogleMap component.

Drawing a Marker

MarkerF component provided by the @react-google-maps/api package can be passed as a children of GoogleMap component to draw a Marker over the map. MarkerF component requires a position prop to specify the latitude and longitude of where to place the Marker.

<GoogleMap
  options={mapOptions}
  zoom={14}
  center={mapCenter}
  mapTypeId={google.maps.MapTypeId.ROADMAP}
  mapContainerStyle={{ width: '800px', height: '800px' }}
  onLoad={(map) => console.log('Map Loaded')}
>
  <MarkerF position={mapCenter} onLoad={() => console.log('Marker Loaded')} />
</GoogleMap>

The icon of the Marker can be changed by specifying an image URL in the icon prop.

<GoogleMap
  options={mapOptions}
  zoom={14}
  center={mapCenter}
  mapTypeId={google.maps.MapTypeId.ROADMAP}
  mapContainerStyle={{ width: '800px', height: '800px' }}
  onLoad={(map) => console.log('Map Loaded')}
>
  <MarkerF
    position={mapCenter}
    onLoad={() => console.log('Marker Loaded')}
    icon="https://picsum.photos/64"
  />
</GoogleMap>

Drawing Circles

We can draw circles over the map using CircleF component provided by the @react-google-maps/api package.

Let’s draw two concentric circles with different radius over the map. We can define properties of the circle such as fill color, fill opacity, stroke color, stroke opacity, etc. using the options prop.

Here, we’ve marked the inner circle as green and the outer circle as red.

<GoogleMap
  options={mapOptions}
  zoom={14}
  center={mapCenter}
  mapTypeId={google.maps.MapTypeId.ROADMAP}
  mapContainerStyle={{ width: '800px', height: '800px' }}
  onLoad={(map) => console.log('Map Loaded')}
>
  <MarkerF position={mapCenter} onLoad={() => console.log('Marker Loaded')} />

  {[1000, 2500].map((radius, idx) => {
    return (
      <CircleF
        key={idx}
        center={mapCenter}
        radius={radius}
        onLoad={() => console.log('Circle Load...')}
        options={{
          fillColor: radius > 1000 ? 'red' : 'green',
          strokeColor: radius > 1000 ? 'red' : 'green',
          strokeOpacity: 0.8,
        }}
      />
    );
  })}
</GoogleMap>

Places Autocomplete

Google Places API can be used to create a autocomplete typeahead dropdown input with suggested addresses.

We will be using use-places-autocomplete library to help build the UI component for the autocomplete input. The library is small, has built in caching and debounce mechanism to reduce API calls to Google APIs.

usePlacesAutcomplete hook can be configured with requestOptions which is the request options of Google Maps Places API

We can specify the number of milliseconds to delay before making a request to Google Maps Places API by using the debounce property. Similarly, cache property would specify the number of seconds to cache the response data from the Google Maps Places API.

The usePlacesAutcomplete hook returns a suggestions object with status and data from the Google Places API. It also provides helper methods to setValue of the input field, clear autocomplete suggestions, clearCache, etc.

const {
  ready,
  value,
  suggestions: { status, data }, // results from Google Places API for the given search term
  setValue, // use this method to link input value with the autocomplete hook
  clearSuggestions,
} = usePlacesAutocomplete({
  requestOptions: { componentRestrictions: { country: 'us' } }, // restrict search to US
  debounce: 300,
  cache: 86400,
});

We create a input field and attach a onChange handler to it which passes the user input value to the autocomplete hook using the setValue() helper method. If we get the OK status form the google places API, we render the suggested results using ul element.

return (
  <div className={styles.autocompleteWrapper}>
    <input
      value={value}
      className={styles.autocompleteInput}
      disabled={!ready}
      onChange={(e) => setValue(e.target.value)}
      placeholder="123 Stariway To Heaven"
    />

    {status === 'OK' && (
      <ul className={styles.suggestionWrapper}>{renderSuggestions()}</ul>
    )}
  </div>
);

The renderSuggestions() is a helper method which uses the data returned from the usePlacesAutcomplete hook and render the list of li elements.

const renderSuggestions = () => {
  return data.map((suggestion) => {
    const {
      place_id,
      structured_formatting: { main_text, secondary_text },
      description,
    } = suggestion;

    return (
      <li
        key={place_id}
        onClick={() => {
          setValue(description, false);
          clearSuggestions();
          onAddressSelect && onAddressSelect(description);
        }}
      >
        <strong>{main_text}</strong> <small>{secondary_text}</small>
      </li>
    );
  });
};

In nutshell, when user starts entering an address in the input field, usePlacesAutocomplete hook would make an API call to Google Places API and return a list of suggestions. We would render those suggestions as selectable list of options.

The PlacesAutocomplete component would look like following:

const PlacesAutocomplete = ({
  onAddressSelect,
}: {
  onAddressSelect?: (address: string) => void;
}) => {
  const {
    ready,
    value,
    suggestions: { status, data },
    setValue,
    clearSuggestions,
  } = usePlacesAutocomplete({
    requestOptions: { componentRestrictions: { country: 'us' } },
    debounce: 300,
    cache: 86400,
  });

  const renderSuggestions = () => {
    return data.map((suggestion) => {
      const {
        place_id,
        structured_formatting: { main_text, secondary_text },
        description,
      } = suggestion;

      return (
        <li
          key={place_id}
          onClick={() => {
            setValue(description, false);
            clearSuggestions();
            onAddressSelect && onAddressSelect(description);
          }}
        >
          <strong>{main_text}</strong> <small>{secondary_text}</small>
        </li>
      );
    });
  };

  return (
    <div className={styles.autocompleteWrapper}>
      <input
        value={value}
        className={styles.autocompleteInput}
        disabled={!ready}
        onChange={(e) => setValue(e.target.value)}
        placeholder="123 Stariway To Heaven"
      />

      {status === 'OK' && (
        <ul className={styles.suggestionWrapper}>{renderSuggestions()}</ul>
      )}
    </div>
  );
};

When user selects an address, we want to re-render the map and center it to the user’s selected address. In order to do that, we need to maintain states for lat and lng and update the state when user selects one of the auto suggested option.

Pass a custom event handler which computes the lat, lng from the selected address and updates the local state. getGeoCode and getLatLng are utility functions provided by use-places-autocomplete hook package.

Adding the PlacesAutocomplete component to the Home component.

const Home: NextPage = () => {
      // Store lat, lng as State Variables
  const [lat, setLat] = useState(27.672932021393862);
  const [lng, setLng] = useState(85.31184012689732);
 // Add lat, lng as dependencies
  const mapCenter = useMemo(() => ({ lat: lat, lng: lng }), [lat, lng]);

    ...

    return (
    <div className={styles.homeWrapper}>
      <div className={styles.sidebar}>
        {/* render Places Auto Complete and pass custom handler which updates the state */}
        <PlacesAutocomplete
          onAddressSelect={(address) => {
            getGeocode({ address: address }).then((results) => {
              const { lat, lng } = getLatLng(results[0]);

              setLat(lat);
              setLng(lng);
            });
          }}
        />
     </div>

         ...
        </div>
    )
}

Conclusion

In this guide, we learned how we can leverage couple of lightweight packages to interact with the google maps API and the google places API to build interactive maps in Next.js

Final Code

index.tsx with Home and PlacesAutoComplete Component.

import {
  useLoadScript,
  GoogleMap,
  MarkerF,
  CircleF,
} from '@react-google-maps/api';
import type { NextPage } from 'next';
import { useMemo, useState } from 'react';
import usePlacesAutocomplete, {
  getGeocode,
  getLatLng,
} from 'use-places-autocomplete';
import styles from '../styles/Home.module.css';

const Home: NextPage = () => {
  const [lat, setLat] = useState(27.672932021393862);
  const [lng, setLng] = useState(85.31184012689732);

  const libraries = useMemo(() => ['places'], []);
  const mapCenter = useMemo(() => ({ lat: lat, lng: lng }), [lat, lng]);

  const mapOptions = useMemo<google.maps.MapOptions>(
    () => ({
      disableDefaultUI: true,
      clickableIcons: true,
      scrollwheel: false,
    }),
    []
  );

  const { isLoaded } = useLoadScript({
    googleMapsApiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_KEY as string,
    libraries: libraries as any,
  });

  if (!isLoaded) {
    return <p>Loading...</p>;
  }

  return (
    <div className={styles.homeWrapper}>
      <div className={styles.sidebar}>
        {/* render Places Auto Complete and pass custom handler which updates the state */}
        <PlacesAutocomplete
          onAddressSelect={(address) => {
            getGeocode({ address: address }).then((results) => {
              const { lat, lng } = getLatLng(results[0]);

              setLat(lat);
              setLng(lng);
            });
          }}
        />
      </div>
      <GoogleMap
        options={mapOptions}
        zoom={14}
        center={mapCenter}
        mapTypeId={google.maps.MapTypeId.ROADMAP}
        mapContainerStyle={{ width: '800px', height: '800px' }}
        onLoad={(map) => console.log('Map Loaded')}
      >
        <MarkerF
          position={mapCenter}
          onLoad={() => console.log('Marker Loaded')}
        />

        {[1000, 2500].map((radius, idx) => {
          return (
            <CircleF
              key={idx}
              center={mapCenter}
              radius={radius}
              onLoad={() => console.log('Circle Load...')}
              options={{
                fillColor: radius > 1000 ? 'red' : 'green',
                strokeColor: radius > 1000 ? 'red' : 'green',
                strokeOpacity: 0.8,
              }}
            />
          );
        })}
      </GoogleMap>
    </div>
  );
};

const PlacesAutocomplete = ({
  onAddressSelect,
}: {
  onAddressSelect?: (address: string) => void;
}) => {
  const {
    ready,
    value,
    suggestions: { status, data },
    setValue,
    clearSuggestions,
  } = usePlacesAutocomplete({
    requestOptions: { componentRestrictions: { country: 'us' } },
    debounce: 300,
    cache: 86400,
  });

  const renderSuggestions = () => {
    return data.map((suggestion) => {
      const {
        place_id,
        structured_formatting: { main_text, secondary_text },
        description,
      } = suggestion;

      return (
        <li
          key={place_id}
          onClick={() => {
            setValue(description, false);
            clearSuggestions();
            onAddressSelect && onAddressSelect(description);
          }}
        >
          <strong>{main_text}</strong> <small>{secondary_text}</small>
        </li>
      );
    });
  };

  return (
    <div className={styles.autocompleteWrapper}>
      <input
        value={value}
        className={styles.autocompleteInput}
        disabled={!ready}
        onChange={(e) => setValue(e.target.value)}
        placeholder="123 Stariway To Heaven"
      />

      {status === 'OK' && (
        <ul className={styles.suggestionWrapper}>{renderSuggestions()}</ul>
      )}
    </div>
  );
};

export default Home;

Home.module.css

.homeWrapper {
  display: flex;
  justify-content: center;
  align-items: center;
}

.sidebar {
  margin-right: 16px;
  width: 20%;
  height: 100vh;
  background-color: #333;
}

.autocompleteWrapper {
  width: 100%;
  height: 100%;
}

.autocompleteInput {
  width: 96%;
  margin: 84px auto 0 auto;
  padding: 16px;
  display: block;
  border: 1px solid yellow;
}

.suggestionWrapper {
  margin: 0;
  width: 96%;
  overflow-x: hidden;
  list-style: none;
  margin: 0 auto;
  display: block;
  padding: 4px;
}

.suggestionWrapper > li {
  padding: 8px 4px;
  background-color: lightcoral;
  margin: 4px 0;
  cursor: pointer;
}

Markdown Blog with Next.js, Typescript and Tailwind

99darshan — Sat, 04 Dec 2021 11:33:35 +0000

This article will discuss how to create a markdown based blog using next.js, typescript and tailwind. This will be a static website, with all the blog posts generated from the markdown files during the build time. We will also look at rendering code blocks with syntax highlighting.

Initialize Project

Create new next.js project with typescript using the following command.
npx create-next-app —-typescript

Tailwind Setup

Install tailwind development dependencies using npm install -D tailwindcss@latest postcss@latest autoprefixer@latest
Use npx tailwindcss init -p command to generate tailwind configuration files tailwind.config.js and postcss.config.js
Since tailwind is a utility first library, by default, it comes with a lot of utility css classes and not all of them are used in our app. Let's use the purge command to tree-shake and remove any unused styles from the production builds. In tailwind.config.js update the purge: [] to purge: ['./pages/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}'].

// tailwind.config.js
module.exports = {
  purge: ['./pages/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}'],
  darkMode: false,
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Import tailwind into the project by adding base, components and utilities styles to the globals.css file generated by next.js

/* ./styles/globals.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

Create Blog Posts Using Markdown

Let's create a sample blog post using markdown for our blog. Create a folder called data and inside that create another folder posts. The posts folder will contain all the markdown files for the blog posts.

Sample blog post hello-world.md

---
title: "Hello World"
description: "First Markdown Based Blog Post"
updatedAt: 2021-08-22
author: Bojack Horseman
---
# Hello World
## Testing
lorem ipsum....
### this is a heading 3
#### heading 4 is this
##### heading five ooooo
###### this is heading six
Random paragraph text. This is a sample markdown blog posts!!

html
<p>dhdhfdh dhfdhf</p>

js
function test(a) {
  console.log('this is a JS code');
}


ruby
def test
    puts('ruby is coool!!!!')
end

![VercelLogo](/images/vercel.svg)

Apart from the regular markdown syntax and the content for the blog, hello-world.md file has some metadata related to the blog posts. These metadata are also referred to as the front-matter and they are defined in the markdown files inside the --- block. front-matter will contain any additional information associated with the blog post.

---
title: Hello World
description: First Markdown Based Blog Post
updatedAt: 2021-08-22
author: Bojack Horseman
---

Defining Models

Let's define few data model that defines the blog post. Let's create a models folder and create couple of files post.ts and frontmatter.ts. Post and Frontmatter types collectively define the attributes of a markdown blog post.

// models/post.ts

import Frontmatter from './frontmatter';

interface Post {
  slug: string;
  content: string;
  frontmatter: Frontmatter;
}

export default Post;

// models/frontmatter.ts

interface Frontmatter {
  title: string;
  description: string;
  author?: string;
  updatedAt?: string;
  createdAt?: string;
}

export default Frontmatter;

Create the Index Page

Inside pages folder create a index.tsx file. The index page will parse all the markdown files from the data/posts folder and render a list of posts title and description.

In Next.js, we can use getStaticProps to write backend code that runs on the server. Any code inside the getStaticProps will run on the server and is executed during the build time. We will use getStaticProps to read the markdown files from the file system and extract the metadata and the markdown content of the blog posts. getStaticProps will return an object which is passed as props to the Home component.

We will use the fs module from node.js to read the markdown files from the files system. Additionally, a package called gray-matter is used to extract the metadata object after parsing the markdown file.

Install gray-matter as development dependency.

npm i --save-dev gray-matter

Get all the files from data/posts directory.

const files = fs.readdirSync(`${process.cwd()}/data/posts`);

Loop through each files and parse each file to string. Now, we can use the matter function from the gray-matter package to retrieve the frontmatter (metadata) and the actual markdown content of the file.

const file = fs.readFileSync(`data/posts/${fileName}`).toString();

// matter returns an object containing data and content keys
// data will have the frontmatter
// and content will have the actual markdown content
const { data, content } = matter(file);

For each file, create post object using the frontmatter and content returned by the matter function call. We will use the file name as a slug. Finally, getStaticProps will return an Array of Post object which will be passed as props to the Home component.

// pages/index.tsx

import fs from 'fs';
import matter from 'gray-matter';

export async function getStaticProps() {
  const files = fs.readdirSync(`${process.cwd()}/data/posts`);

  const posts: Array<Post> = files.map((fileName) => {
    const file = fs.readFileSync(`data/posts/${fileName}`).toString();

    const { data, content } = matter(file);
    const frontmatter = { title: data.title, description: data.description };

    return {
      slug: fileName.replace('.md', ''),
      content: content,
      frontmatter,
    };
  });

  return {
    props: {
      posts,
    },
  };
}

Create and export a Home component on the index page. The Home component will receive an array of Post and render a list of post title and description.

// pages/index.tsx

import Link from 'next/link';

type HomeProps = {
  posts: Array<Post>;
};

const Home: NextPage<HomeProps> = ({ posts }: HomeProps) => {
  return (
    <div>
      <main className="container mx-auto py-8 px-4 md:px-0 flex flex-col">
        <h2 className="text-6xl text-bold font-serif text-yellow-800">
          Sloth Blog
        </h2>
        <div className="my-6 flex-col">
          {posts.map((post, idx) => {
            return (
              <Link href={`/posts/${post.slug}`} key={idx} passHref={true}>
                <div className="w-max py-2">
                  <h3 className="text-2xl text-bold font-sans">
                    {post.frontmatter.title}
                  </h3>
                  <p className="text-sm font-thin">
                    {post.frontmatter.description}
                  </p>
                </div>
              </Link>
            );
          })}
        </div>
      </main>
    </div>
  );
};

export default Home;

With the magic of tailwind utility classes and a simple markup, we have a basic looking index page for our blog. Notice that we have used the Link component provided by next.js. Link component acts as an anchor tag and accepts an href prop. We use the slug to identify each blog post and will redirect to blog post URL /posts/{slug}.

Create Post Page

When clicked on one of the blog posts in the index page, it redirects to the posts page to read the post content. However, we haven't created the post page yet. Let's create a [slug].tsx file inside pages/posts directory.

We will use dynamic route feature of Next.js to dynamically generate the posts pages. For each markdown file in data/posts folder, we want to tell Next.js to generate individual pages during the build time. If we have 100 markdown files in our blog, Next.js will statically generate 100 html pages during build time.

getStaticPaths function allows us to create dynamic routes based on the parameters passed in, which in our case is the slug. In getStaticPaths it reads all the files in data/posts directory and return an array of objects. Each object must have the params key and contain an object with the slug key since we are using [slug] in the file name. After creating a dynamic routes, getStaticPaths passes the current slug received as a query param to the getStaticProps method.

// pages/posts/[slug].tsx
import fs from 'fs';

export async function getStaticPaths() {
  const files = fs.readdirSync(`${process.cwd()}/data/posts`);

  const paths = files.map((fileName) => {
    return {
      params: {
        slug: fileName.replace('.md', ''),
      },
    };
  });

  return {
    paths,
    fallback: false,
  };
}

getStaticProps receives the params.slug from getStaticPath . getStaticProps makes use of the slug params to parse the markdown down and pass the frontmatter and markdown content to the PostPage component.

// pages/posts/[slug].tsx

import fs from 'fs';
import matter from 'gray-matter';

export async function getStaticProps({
  params: { slug },
}: {
  params: { slug: string };
}) {
  const file = fs.readFileSync(`data/posts/${slug}.md`).toString();
  const { data, content } = matter(file);

  return {
    props: {
      slug,
      content,
      frontmatter: { title: data.title, description: data.description },
    },
  };
}

Next step is to create the PostPage component that renders the blog post. PostPage component would receive a Post object as props from the getStaticProps method.

// pages/posts/[slug].tsx

const PostPage: NextPage<Post> = ({ slug, content, frontmatter }: Post) => {
  return (
    <main className="container mx-auto px-3 py-4 md:px-0">
      <article>
        <p>{content}</p>
      </article>
    </main>
  );
};

The above PostPage component renders the markdown content as a plain text. At this point our page looks like below, entire markdown content rendered as a plain text.

Render Markdown as HTML

We want to convert the markdown content raw string to corresponding HTML tags and render the markdown as an HTML. For this we will use a package called React Markdown.

Install react-markdown package using npm i react-markdown

In PostPage component, let's wrap the markdown content with the ReactMarkdown component. ReactMarkdown accepts the markdown content as a children and it renders the markdown as an HTML.

// pages/posts/[slug].tsx

import ReactMarkdown from 'react-markdown';

const PostPage: NextPage<Post> = ({ slug, content, frontmatter }: Post) => {
  return (
    <main className="container mx-auto px-3 py-4 md:px-0">
      <article>
        <ReactMarkdown>{content}</ReactMarkdown>
      </article>
    </main>
  );
};

Now the post page will render the markdown content as HTML.

Styling the markdown content using tailwind typography

Now that the markdown content is rendered as HTML, it's time to make it look good. However, we don't want to define CSS styles on each of the markdown files. By default, tailwind CSS resets all the browsers default styles on all DOM elements, so default styles for headings, paragraphs and anchor tags are not yet defined.

Tailwind provides a typography plugin to apply sensible defaults to our HTML content rendered from Markdown.

Install tailwind typography plugin using npm install @tailwindcss/typography and add it to the plugins array in tailwind.config.js e.g.

plugins: [require('@tailwindcss/typography')]

Next step is to add prose class to the html tag wrapping the ReactMarkdown component.

// [slug].tsx
// add prose css class to article tag
const PostPage: NextPage<Post> = ({ slug, content, frontmatter }: Post) => {
  return (
    <main className="container mx-auto px-3 py-4 md:px-0">
      <article className="prose">
        <ReactMarkdown>{content}</ReactMarkdown>
      </article>
    </main>
  );
};

With the default styles our post page now looks like this.

We can override default styles set by tailwind typography plugin by extending the tailwind theme.

// tailwind.config.js
module.exports = {
  purge: ['./pages//*.{js,ts,jsx,tsx}', './components//*.{js,ts,jsx,tsx}'],
  darkMode: false,
  theme: {
    extend: {
      // override default styles from typography plugin
      typography: (theme) => ({
        DEFAULT: {
          css: {
            h1: {
              color: '#FF5C58',
            },
          },
        },
      }),
    },
  },
  variants: {
    extend: {},
  },
  plugins: [require('@tailwindcss/typography')],
};

Using Syntax Highlighter to highlight codeblocks

Using tailwind typography plugin, our post page have some basic styling. However, it still lacks the syntax highlighting for the code blocks. For this we will use a package called react-syntax-highlighter.

Install react-syntax-highlighter and the it's corresponding type definitions for Typescript.

npm install react-syntax-highlighter

npm install -D @types/react-syntax-highlighter

In PostPage component, we used ReactMarkdown to convert markdown content to equivalent HTML tags. ReactMarkdown provides a way to overwrite the default handling of any DOM elements by passing a components params. Here, we would overwrite the default handling of code element by passing our custom implementation using the react-syntax-highlighter

// [slug].tsx
import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
import {
  dark,
  dracula,
  prism,
} from 'react-syntax-highlighter/dist/cjs/styles/prism';

const PostPage: NextPage<Post> = ({ slug, content, frontmatter }: Post) => {
  return (
    <main className="container mx-auto px-3 py-4 md:px-0">
      <article className="prose">
        <ReactMarkdown
          components={{
            code({ node, inline, className, children, ...props }: any) {
              const match = /language-(\w+)/.exec(className || '');
              return !inline && match ? (
                <SyntaxHighlighter
                  style={dracula} // try passing different color schemes, drak, dracula etc.
                  language={match[1]}
                  PreTag="div"
                  {...props}
                >
                  {String(children).replace(/\n$/, '')}
                </SyntaxHighlighter>
              ) : (
                <code>{children}</code>
              );
            },
          }}
        >
          {content}
        </ReactMarkdown>
      </article>
    </main>
  );
};

Our Post Page finally looks like this, with syntax
highlighting for the specified language.

Flutter App for AWS whitepapers and Guides

99darshan — Wed, 01 Dec 2021 13:03:58 +0000

After around 2K lifetime downloads and 600 daily active users, the flutter app to browse, read, save and download AWS whitepapers and guide is now open-sourced.

This is a reference mobile app of AWS whitepapers and guides website.

View Code at Github

Download App on Play Store

Trying Out Electron JS

99darshan — Wed, 20 Jan 2021 16:01:27 +0000

I wanted to try out Electron JS and get started with the basics by creating a simple app that I'll be using myself on a daily basis. I chose to create a Mac menubar application to render devdocs.io. I am a huge fan of devdocs.io and use it frequently so I thought it will be super handy to have all the documentation right on the menu bar.

Since this is my first attempt at using Electron, this article will document the steps I took to develop the application.

Create project folder

mkdir menubar-dev-docs

cd menubar-dev-docs

Initialize npm package

npm init -y

Typescript configuration

npm install typescript --save-dev

tsc --init creates a typescript config file tsconfig.json.

Add electron as dev dependency

npm install electron --save-dev

Webpack setup

We will use webpack to bundle and build the application.

Install webpack related dev dependencies

npm install webpack webpack-cli ts-loader --save-dev

Create webpack.config.js in the root folder and use the code below. We are specifying ./src/main.ts as the entry point of our application. Webpack will build it and output a bundled minified version as main.js inside /dist folder

const path = require('path');

// Electron Webpack Configuration
const electronConfiguration = {
  // Build Mode
  mode: 'development',
  // Electron Entrypoint
  entry: './src/main.ts',
  target: 'electron-main',
  resolve: {
    alias: {
      ['@']: path.resolve(__dirname, 'src'),
    },
    extensions: ['.tsx', '.ts', '.js'],
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        include: /src/,
        use: [{ loader: 'ts-loader' }],
      },
    ],
  },
  output: {
    path: __dirname + '/dist',
    filename: 'main.js',
  },
};

module.exports = [electronConfiguration];

Create main script file `src/main.ts`

The main.ts is the main entry point to an Electron application. This file runs the electron main process which controls the lifecycle of the application, graphical user interface and the renderer processes. An Electron app can have only one main process but have multiple renderer processes.

import { app, BrowserWindow } from 'electron';

const createWindow = (): void => {
  const mainWindow = new BrowserWindow({
    width: 1020,
    height: 800,
  });

  mainWindow.loadURL('https://devdocs.io');
};

// call createWindow method on ready event
app.on('ready', createWindow);

When app initializes, electron fires a ready event. Once app is loaded createWindow callback function is called. createWindow creates a BrowserWindow object with height and width property and loads devdocs.io URL.

The BrowserWindow object represents the Renderer process (web page). We can create multiple browser windows, where each window uses its own independent Renderer.

Start the application

At this point we should be able to start our application and see it running. In order to run the application we need to specify two scripts inside scripts section of package.json

  "scripts": {
    "compile": "webpack",
    "start": "npm run compile && electron dist/main.js"
  },

compile script will trigger webpack to compile the application and output the bundled main.js file inside the dist folder. start script will invoke the compile script first and initiate electron to execute the build output file dist/main.js

Once we have these script setup, we can start the application by using npm start

We now have a screen rendering devdocs.io webpage. The ultimate goal however is to have it as a menu bar app.

Menubar Tray Object

Next step will be to create a mac menubar tray element and toggle the BrowserWindow using the tray element.

Electron provides a Tray class to add icons and context menu to the notification area of the menu bar.

Let's create a class called TrayGenerator which takes in an object of BrowserWindow and string path for the app icon and creates a Tray object. The browser window that was created previously in main.js would be toggled using the Tray icon from the menubar.

import { app, Tray, BrowserWindow, nativeImage, Menu } from 'electron';

class TrayGenerator {
  tray: Tray;

  constructor(public mainWindow: BrowserWindow, public iconPath: string) {
    this.createTray();
  }
}

TrayGenerator class has a public property called tray to access to Tray object. createTray() method is called on the constructor when TrayGenerator object is initialized. createTray() method creates the Tray object and toggles the browser window on click.

Add a private method createTray() to the TrayGenerator class

  private createTray = () => {
    this.tray = new Tray(this.createNativeImage());
    this.tray.setIgnoreDoubleClickEvents(true);
    this.tray.on('click', this.toggleWindow);
  }

Tray object requires a NativeImage object during initialization. Add another private method createNativeImage() to the TrayGenerator class which creates an object of NativeImage

  private createNativeImage() {
    // Since we never know where the app is installed,
    // we need to add the app base path to it.
    let appPath = app.getAppPath();
    appPath = appPath.endsWith('dist') ?  appPath : `${appPath}/dist`
    const path = `${appPath}/${this.iconPath}`;
    const image = nativeImage.createFromPath(path);
    // Marks the image as a template image.
    image.setTemplateImage(true);
    return image;
  }

Finally we need add a method toggle window when the menubar Tray icon is clicked. Add two more private methods toggleWindow() and showWindow() to the TrayGenerator class.

  private toggleWindow = () => {
    const isVisible = this.mainWindow.isVisible();
    const isFocused = this.mainWindow.isFocused();

    if (isVisible && isFocused){
      this.mainWindow.hide();
    } else if (isVisible && !isFocused){
      this.mainWindow.show();
      this.mainWindow.focus();
    } else {
      this.showWindow();
    }
  };

  private showWindow = () => {
    // set the position of the main browser window
    this.mainWindow.setPosition(this.tray.getBounds().x, 0, false);
    this.mainWindow.show();
    this.mainWindow.setVisibleOnAllWorkspaces(true); // put the window on all screens
    this.mainWindow.focus();  // focus the window up front on the active screen
    this.mainWindow.setVisibleOnAllWorkspaces(false); // disable all screen behavior
  };

TrayGenerator class finally look like below:

import { app, Tray, BrowserWindow, nativeImage, Menu } from 'electron';

class TrayGenerator {
  tray: Tray;

  constructor(public mainWindow: BrowserWindow, public iconPath: string) {
    this.createTray();
  }

  private createTray = () => {
    this.tray = new Tray(this.createNativeImage());
    this.tray.setIgnoreDoubleClickEvents(true);
    this.tray.on('click', this.toggleWindow);
  };

  private createNativeImage() {
    // Since we never know where the app is installed,
    // we need to add the app base path to it.
    // on dev env, the build app is dist, once packaged electron-builder package it as dist/assets, but app path is not in dist so append dist for pacaking
    let appPath = app.getAppPath();
    appPath = appPath.endsWith('dist') ? appPath : `${appPath}/dist`;
    const path = `${appPath}/${this.iconPath}`;
    const image = nativeImage.createFromPath(path);
    // Marks the image as a template image.
    image.setTemplateImage(true);
    return image;
  }

  private toggleWindow = () => {
    const isVisible = this.mainWindow.isVisible();
    const isFocused = this.mainWindow.isFocused();

    if (isVisible && isFocused) {
      this.mainWindow.hide();
    } else if (isVisible && !isFocused) {
      this.mainWindow.show();
      this.mainWindow.focus();
    } else {
      this.showWindow();
    }
  };

  private showWindow = () => {
    this.mainWindow.setPosition(this.tray.getBounds().x, 0, false);
    this.mainWindow.show();
    this.mainWindow.setVisibleOnAllWorkspaces(true); // put the window on all screens
    this.mainWindow.focus(); // focus the window up front on the active screen
    this.mainWindow.setVisibleOnAllWorkspaces(false); // disable all screen behavior
  };
}

export default TrayGenerator;

Use TrayGenerator to create Tray object on the app ready event specified in main.ts

// call createWindow method on ready event
app.on('ready', () => {
  createWindow();
  const trayGenerator: TrayGenerator = new TrayGenerator(
    mainWindow,
    'assets/IconTemplate.png'
  );
  tray = trayGenerator.tray;
});

Note that the mainWindow object is created when we call the createWindow() method and the mainWindow is defined in the global scope. We moved the mainWindow from the fuction scope to global so that the object is not lost from the memory during garbage collection.

The final main.ts file:

import { app, BrowserWindow, Tray } from 'electron';
import TrayGenerator from './TrayGenerator';

// NOTE: declare mainWindow and tray as global variable
// tray will be created out of this mainWindow object
// declaring them inside createWindow will result in tray icon being lost because of garbage collection of mainWindow object
let mainWindow: BrowserWindow;
let tray: Tray;

const createWindow = (): void => {
  mainWindow = new BrowserWindow({
    width: 1020,
    height: 800,
    frame: false, // hide the app window frame
    show: false, // do not load main window on app load
    fullscreenable: false, // prevent full screen of main window
    resizable: true, // allow resizing the main window
    alwaysOnTop: false,
  });

  mainWindow.loadURL('https://devdocs.io');
};

// call createWindow method on ready event
app.on('ready', () => {
  createWindow();
  const trayGenerator: TrayGenerator = new TrayGenerator(
    mainWindow,
    'assets/IconTemplate.png'
  );
  tray = trayGenerator.tray;
});

This was a quick experiment to get started with the basics of Electron JS.

Links:

Github Repo: HERE

Download dmg file: HERE

Introduction to Extension Methods in C#

99darshan — Wed, 15 Apr 2020 17:39:14 +0000

Introduction

Extension Methods, as the name suggests, are methods used to extend the functionality of any C# types without having to directly modify and re-compile the original type itself.

General format of Extension methods in C#

    public static class ClassName
    {
        public static ReturnType ExtensionMethodName(this TypeToWhichExtMethodWillBeAdded t)
        {
            // Extension Method definition
        }
    }

Use Case

Extension methods are typically used whenever there is a need to add certain functionality to any C# types which are available as an external library or ".dll". In cases where the source code of external library is unavailable or restricted for modifications, C# extension methods can be used to extend the functionality of certain class or struct provided in that external library.

Example Scenario

Consider the following scenario, C# has an inbuilt Class Random in System Namespace which can be used to generate random numbers. Next() method defined in Random class generates a random number.

Now, let's say we want to generate random English alphabet instead of random number. However, there is no in-built method in the Random class which allows us to do that. And since Random is an inbuilt type provided by C#, we can not directly modify the class itself and add a new method to generate random alphabet.

Random number generation using inbuilt method in Random Class

    using System;

    namespace ExtensionMethodDemo
    {
        class Program
        {
            static void Main(string[] args)
            {   
                Random rnd = new Random();
            // Next() method returns a random integer
                int randomNum = rnd.Next(); 
                Console.WriteLine("random Num " + randomNum);
            }
        }
    }

Output: random Num 1854662654

Adding NextAlphabet() extension method to the Random Class

We can create an Extension Method named NextAlphabet() and use it as if it was defined in the Random class itself.

using System;

namespace ExtensionMethodDemo
{
   public static class ExtensionMethods
   {
      // Extension Method which return random english letter
      public static char NextAlphabet(this Random rnd)
      {
         int rndIndex = rnd.Next(0, 26);
         return (char)('a' + rndIndex);
      }
    }
}

Using NextAlphabet() Extension Method:

    using System; 
    namespace ExtensionMethodDemo
    {
        class Program
        {
            static void Main(string[] args)
            {   
                Random rnd = new Random();
            // Next() method returns a random integer
                int randomNum = rnd.Next(); 
                Console.WriteLine("random Num " + randomNum);

            // EXTENSION METHOD NextAlphabet()
                // Extension method are called exactly like instance method
                char randomLetter = rnd.NextAlphabet();
                Console.WriteLine("Random Letter: " + randomLetter);
            }
        }
    }

Output:

random Num 1066262963
Random Letter: q

Points to note about C# extension methods

C# extension methods must be defined in a static class. In the example above, all extension methods are inside static class ExtensionMethods.
C# extension methods must be defined as static.
Unlike regular static method in C#, extension method must have the first parameter preceded by "this" keyword. The first parameter with "this" keyword specifies the type for which the extension method is being added. In the example below, we are adding NextAlphabet() extension method to the type of System.Random class.

    // Note the static and this Keyword in Extension Method Signature
    public static char NextAlphabet(this Random rnd)
    {
        // ...
    }

Even though extension methods are defined as static method, they are invoked exactly like an instance method. An instance of that type needs to be created before calling extension methods. Since first parameter with the "this" keyword specifies the type for which extension method is defined, it shouldn't be passed as an argument when calling the extension method.

    // Calling an extension method
    Random rnd = new Random();
    // invoked like any other instance method of Random Class
    char randomLetter = rnd.NextAlphabet();

Extension method with additional parameter

Any additional parameters to the extension methods must be added to the parameter list after the first parameter.

Now let's create an extension method for Random Class which returns a random item from any given list passed as an argument.

    public static string PickRandom(this Random rnd, List<string> list)
    {
        int rndIndex = rnd.Next(0, list.Count);
        return list[rndIndex];
    }

Using PickRandom() Extension Method

    using System;
    using System.Collections.Generic;
    namespace ExtensionMethodDemo
    {
        class Program
        {
            static void Main(string[] args)
            {   
            Random rnd = new Random();
                List<string> names = new List<string> { "Ronaldo", "Hazard", "Messi", "Lampard" };
                // list names is passed as an argument to the extension method
            string randomName = rnd.PickRandom(names);
                Console.WriteLine("Random Name: " + randomName);
            }
        }
    }

Output: Random Name: Lampard

Identifying extension methods in visual studio

Visual studio has a separate icon to distinguish normal methods from extension methods. Extension Methods are identified by an icon with a little downward arrow to the right of pink cube.

Additional notes about C# extension methods

Extension methods can be applied to any types including value types, however, they can't be applied to fields or properties.
When creating an extension method make sure that a method with same name and method signature doesn't exist in the original type itself. If the method name and method signature of extension method matches an instance method in the original type, then the instance method will be invoked instead of extension method.

Conclusion

C# extension method are useful to add functionality to types where the modifications to the original source code can't be made.
Since extension methods eliminate the need to create a new derived type in our project, it improves the readability of our code.

REST API versioning with ASP.NET Core

99darshan — Thu, 16 Jan 2020 09:47:04 +0000

The best way to version a RESTful API is a topic of constant debate and every other approach have their own pros and cons. There is no 'one size fits all' solution when it comes to versioning a REST API.

This article will discuss some of the commonly used API Versioning strategies and demonstrate how to implement them in ASP.NET Core Web API.

Challenges of API versioning

The most RESTful way of versioning an API is to not version it at all. However, over time requirements change and API should evolve accordingly to accommodate those changes. It is imperative to anticipate changes and think about a versioning strategy before publishing the first version of the API. Once the API is published, any future changes to the API should not break the existing client app consuming the API.

In typical projects like class libraries or executable programs we could achieve versioning by creating a different version of a package, typically by changing assemblies version. What makes API versioning difficult is that multiple versions of API should be supported at the same time. Old clients may still rely on the older version and new clients would want to make use of the latest API. Side by side deployment of multiple version of API on the server is impractical and inconvenient. The approach to versioning the REST API is to support multiple versions in the same code base.

REST API Versioning in .Net Core

Implementing a versioning strategy into .NET Core web API from the ground up can be a challenge. Microsoft has provided a Nuget package called Microsoft.AspNetCore.Mvc.Versioning to ease the process versioning .Net Core REST APIs.

Getting started

Create a new .NET core web API project. Add Microsoft.AspNetCore.Mvc.Versioning Nuget package as a dependency to the project and add API Versioning package into the service container of the project.

// startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    // Add API Versioning to the service container to your project
    services.AddApiVersioning();
}

Configuring the Default Behavior for API Versioning

If a GET request is made to the values resource (/api/values endpoint), 404 Bad Request response is returned. This happens because the default behavior of API versioning package expects to specify the API version in all cases.

GET /api/values

{
    "error": {
        "code": "ApiVersionUnspecified",
        "message": "An API version is required, but was not     
specified.",
        "innerError": null
    }
}

Use a lambda function to configure API versioning and specify the default API version number and use that default API version number when no API version is specified.

// startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    // Add API Versioning to as service to your project 
    services.AddApiVersioning(config =>
    {
        // Specify the default API Version as 1.0
        config.DefaultApiVersion = new ApiVersion(1, 0);
        // If the client hasn't specified the API version in the request, use the default API version number 
        config.AssumeDefaultVersionWhenUnspecified = true;
    });
}

Now if a request is made to the values resource (api/values) without specifying the API version, server will respond with a 200 OK. Since the API version was not specified in the request, the default version of 1.0 is assumed. Furthermore, values controller is not specified with any version number, the values controller is also assumed to be of the default version.

Advertise the accepted API Version to the client

When configuring the API Versioning, set ReportApiVersion property to true to let the consumers know about the supported API versions.

// startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    // Add API Versioning to as service to your project 
    services.AddApiVersioning(config =>
    {
        // Specify the default API Version
        config.DefaultApiVersion = new ApiVersion(1, 0);
        // If the client hasn't specified the API version in the request, use the default API version number 
        config.AssumeDefaultVersionWhenUnspecified = true;
        // Advertise the API versions supported for the particular endpoint
        config.ReportApiVersions = true;
    });
}

Now a GET request to the values endpoint will respond with a 200 OK and contain response header named api-supported-versions which lists all available API versions for that endpoint.

Advertising the supported versions for an API can be really useful for the API consumers. The consumers could read the api-supported-versions header and figure out what versions are supported for that particular endpoint.

Version specific Controllers and Actions

When the clients make request for a specific version of an API endpoint, the request should be redirected to the appropriate controller or action handling the requested API version. There are multiple approaches on how to assign controllers and actions to handle version specific requests. Separate controllers can be created for each API versions and the request will be directed to a particular controller based on the requested API version. This article however, will demonstrate on creating all the version specific actions within a single controller.

First step is to specify what API versions are supported by the controller using the ApiVersion attribute. Code snippet below specify and advertise that the values controller accepts API v1.0 and v1.1. Separate actions to handle requests based on the API version has not been created yet.

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;

namespace apiVersioningDemo.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    [ApiVersion("1.0")]
    [ApiVersion("1.1")]
    public class ValuesController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        [HttpGet("{id}")]
        public ActionResult<string> Get(int id)
        {
            return "value";
        }
   }
}

Since no version number is specified to the actions in values controller, all the endpoints are assumed to have the default version of 1.0.
Add a new action method for the GET values endpoint to handle API version 1.1 using MapToApiVersion attribute.

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;

namespace apiVersioningDemo.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    [ApiVersion("1.0")]
    [ApiVersion("1.1")]
    public class ValuesController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values
        [HttpGet]
        [MapToApiVersion("1.1")] // v1.1 specific action for GET api/values endpoint
        public ActionResult<IEnumerable<string>> GetV1_1()
        {
            return new string[] { "version 1.1 value 1", "version 1.1 value2 " };
        }
  }
}

In the above code snippet, GET request for v1.0 is handled by the Get() action while GET request for v1.1 is handled by the GetV1_1() action.

Versioning strategies

Now that the API supports multiple version, we need a way to allow clients to specify the API version they are requesting. There few different approaches on how to allow clients to send the versioning information when making the request. Some of these strategies are discussed below:

Using query params

The default versioning scheme provided by the Microsoft.AspNetCore.Mvc.Versioning package makes use of a query param api-version.

Versioning an API using a query string allows for clients to explicitly specify the version number based on their need. Unlike other versioning strategies, clients do not need to include API version info in every request. If the api-version query string is not specified by the client, the default version is implicitly requested.

https://demo.org/api/resource?api-version=1.1

Using Request Headers

Another approach to versioning an API is using request headers where a header value specifies the API version. Many developers advocate this approach because unlike the URL path param and query string approach, using request header doesn't require fiddling around with the URLs on the client side. The downside to using request headers for versioning is that the versioning option is not explicitly visible to the client at a first glance.

By default Microsoft.AspNetCore.Mvc.Versioning package makes use of query param strategy to specify the API version in the request. Configure the API Versioning to use request headers as a versioning strategy using a Version Reader. ApiVersionReader is used to specify the versioning scheme, this class analyzes the request and figure out which version is being requested. If unspecified, the default version reader scheme is QueryStringApiVersionReader, that's why we were able to request v1.1 using the api-version query params earlier.

Changing the version reader to HeaderApiVersionReader enable clients to send the versioning information using the request header instead of query params. API Version can be specified by the client in the X-version header. Note that "X-version" string which is passed as a parameter to the HeaderApiVersionReader() method is an arbitrary name chosen for the request header used for sending API version information.

        // startup.cs
        public void ConfigureServices(IServiceCollection services)
        {
              services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            // Add API Versioning to as service to your project 
            services.AddApiVersioning(config =>
            {
                // Specify the default API Version
                config.DefaultApiVersion = new ApiVersion(1, 0);
                // If the client hasn't specified the API version in the request, use the default API version number 
                config.AssumeDefaultVersionWhenUnspecified = true;
                // Advertise the API versions supported for the particular endpoint
                config.ReportApiVersions = true;

                // DEFAULT Version reader is QueryStringApiVersionReader();  
                // clients request the specific version using the X-version header
                config.ApiVersionReader = new HeaderApiVersionReader("X-version");
            });
        }

Using Media Type (Accept header) Versioning

Another approach of version the API is using the content negotiation process provided by HTTP. When client requests a resource using the Accept header, they could explicitly include the version number in the media type itself.

In GET request to the values endpoint shown below, the client is explicitly mentioning that it accepts the response of media type application/json with a version number of 1.1 from the server.

GET /values
Accept: application/json;v=1.1

Server could read the Accept header from the request, and respond with the appropriate API version.

One of the disadvantages of using Media Type versioning scheme is that it can be quite obscure, difficult to implement and not immediately obvious to clients that they can request different API versions using the Accept header.

To implement versioning using media type set the ApiVersionReader to a instance of MediaTypeApiVersionReader class.

public void ConfigureServices(IServiceCollection services)
{
             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            // Add API Versioning to as service to your project 
            services.AddApiVersioning(config =>
            {
                // Specify the default API Version
                config.DefaultApiVersion = new ApiVersion(1, 0);
                // If the client hasn't specified the API version in the request, use the default API version number 
                config.AssumeDefaultVersionWhenUnspecified = true;
                // Advertise the API versions supported for the particular endpoint
                config.ReportApiVersions = true;

                // Versioning using media type
                config.ApiVersionReader = new MediaTypeApiVersionReader("v");

            });
}

Using URL path versioning scheme

Using a version number directly in the URL path is one of the simplest way of versioning an API. URL path versioning approach is more visible since it explicitly states the version number in the URL itself. However, this approach mandates clients to change their URL across their application whenever there is a new API version. Furthermore, embedding the API version into the URL itself would break a fundamental principle of REST API which states that each URL should represent a particular resource and the resource URL should not change over time. This approach is better suited in cases when every new API version has broad major changes.

https://demo.org/api/v2/resource

To implement URL path versioning, modify the Route attribute of the controllers to accept API versioning info in the path param.

The Route attribute is changed to :

[Route("api/v{version:apiVersion}/[controller]")]

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;

namespace apiVersioningDemo.Controllers
{
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiController]
    [ApiVersion("1.0")]
    [ApiVersion("1.1")]
    public class ValuesController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values
        [HttpGet]
        [MapToApiVersion("1.1")] // v1.1 specific action for GET api/values endpoint
        public ActionResult<IEnumerable<string>> GetV1_1()
        {
            return new string[] { "version 1.1 value 1", "version 1.1 value2 " };
        }
  }
}

Supporting multiple versioning Schemes

Supporting for multiple API versioning schemes provide flexibility and give options to the clients to use the versioning scheme of their choice. The code snippet below demonstrate how to provide support for both the query params versioning scheme and request header versioning scheme using the static method Combine avaliable in the ApiVersionReader class.

 public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            // Add API Versioning to as service to your project 
            services.AddApiVersioning(config =>
            {
                // Specify the default API Version
                config.DefaultApiVersion = new ApiVersion(1, 0);
                // If the client hasn't specified the API version in the request, use the default API version number 
                config.AssumeDefaultVersionWhenUnspecified = true;
                // Advertise the API versions supported for the particular endpoint
                config.ReportApiVersions = true;

                // DEFAULT Version reader is QueryStringApiVersionReader();  
                // clients request the specific version using the X-version header
                //config.ApiVersionReader = new HeaderApiVersionReader("X-version");

                // Supporting multiple versioning scheme
                config.ApiVersionReader = ApiVersionReader.Combine(new HeaderApiVersionReader("X-version"), new QueryStringApiVersionReader("api-version"));
            });
        }

Now that two different API versioning schemes are supported, the clients should make sure to use only one of the supported schemes. Technically clients could use both the schemes to specify the API version in a request as long as they specify the same version number. If two different versions are requested in the same request using the different API versioning scheme, it will result in a bad request error.

In the above example, API v1.0 is requested using the query param scheme and v1.1 is requested using the header scheme, which results in the Ambiguous Api Version error.

Advertising the Deprecated Versions

Similar to advertising the supported API versions for an endpoint, API versions which will be deprecated in the near future can also be advertised by setting the deprecated property to true in the ApiVersion attribute. The client could read the api-deprecated-versions in the response header and identify the deprecated API versions.

using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;

namespace apiVersioningDemo.Controllers
{
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiController]
    // DEPRECATING an API Version
    [ApiVersion("1.0", Deprecated = true)]
    [ApiVersion("1.1")]
    public class ValuesController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values
        [HttpGet]
        [MapToApiVersion("1.1")] // v1.1 specific action for GET api/values endpoint
        public ActionResult<IEnumerable<string>> GetV1_1()
        {
            return new string[] { "version 1.1 value 1", "version 1.1 value2 " };
        }
  }
}

Conclusion

This article discussed about multiple approaches for versioning a REST API in .NET Core. Depending on the given use case and the consumer of the API, an appropriate versioning strategy can be implemented.

DEV Community: 99darshan

Build Interactive Maps in Next.js using Google Maps API

Demo

Project Setup

Create Google Cloud API Key

Rendering Map

Drawing Over the Map

Drawing a Marker

Drawing Circles

Places Autocomplete

Conclusion

Final Code

Markdown Blog with Next.js, Typescript and Tailwind

Initialize Project

Tailwind Setup

Create Blog Posts Using Markdown

Defining Models

Create the Index Page

Create Post Page

Render Markdown as HTML

Styling the markdown content using tailwind typography

Using Syntax Highlighter to highlight codeblocks

Flutter App for AWS whitepapers and Guides

Trying Out Electron JS

Create project folder

Initialize npm package

Typescript configuration

Add electron as dev dependency

Webpack setup

Create main script file src/main.ts

Start the application

Menubar Tray Object

Links:

Introduction to Extension Methods in C#

Introduction

Use Case

Example Scenario

Points to note about C# extension methods

Extension method with additional parameter

Identifying extension methods in visual studio

Additional notes about C# extension methods

Conclusion

REST API versioning with ASP.NET Core

Challenges of API versioning

REST API Versioning in .Net Core

Getting started

Configuring the Default Behavior for API Versioning

Advertise the accepted API Version to the client

Version specific Controllers and Actions

Versioning strategies

Using query params

Using Request Headers

Using Media Type (Accept header) Versioning

Using URL path versioning scheme

Supporting multiple versioning Schemes

Advertising the Deprecated Versions

Conclusion

Create main script file `src/main.ts`