Your first Nitric API using Python

Hey Dev.to community!

Today we are diving into an exciting project where we'll create a Profile Management API using Nitric and Python.

This API will handle the creation, updating, and deletion of user profiles. We’ll then extend it to manage profile images.

1. Use Nitric to create an API to create and update profiles
2. Create handlers for the following API operations

1. Run locally for testing
2. Deploy to a cloud of your choice
3. (Optional) Add handlers for the following API operations

Prerequisites

• Pipenv
• The Nitric CLI
• An AWS, GCP or Azure account (your choice)

Introducing Nitric

Nitric is a tool that helps developers create applications for the cloud (like AWS, Google Cloud, or Microsoft Azure) quickly and with less repetitive code. It acts as a bridge between your code and the cloud services, making it dead simple to build and deploy your application.

By using Nitric, you can focus more on building your application, and less on the specifics of the cloud provider and eliminate the Terraform (or other IaC) project required to deploy it.

Learn more about it by checking out some of my other blogs, or heading to the docs.

Let's Code

We'll start by creating a new project for our API.

nitric new my-profile-api py-starter

Next, open the project in your editor of choice.

cd my-profile-api

Make sure all dependencies are resolved:

pipenv install --dev

The scaffolded project should have the following structure:

+--services/
|  +-- hello.py
+--nitric.yaml
+--Pipfile
+--Pipfile.lock
+--README.md

You can test the project to verify everything is working as expected:

nitric start

If everything is working as expected you can now delete all files in the services/ folder, we'll create new services in this guide.

Building the Profile API

Let's start building our profiles API. Create a file named 'profiles.py' in the services directory and add the following:

from uuid import uuid4

from nitric.resources import api, kv, bucket
from nitric.application import Nitric
from nitric.context import HttpContext

# Create an api named public
profile_api = api("public")

# Access profile key value store with permissions
profiles = kv('profiles').allow('getting', 'setting')

Nitric.run()

Here we're creating:

• An API named public,
• A key value store named profiles and giving our service permission to get and set to that store.

You could separate some or all of these request handlers into their own
functions if you prefer. For simplicity we'll group them together in this
guide.

Create profiles with POST

@profile_api.post("/profiles")
async def create_profile(ctx: HttpContext) -> None:
  pid = str(uuid4())
  name = ctx.req.json['name']
  age = ctx.req.json['age']
  hometown = ctx.req.json['homeTown']

  await profiles.set(pid, { 'name': name, 'age': age, 'hometown': hometown} )

  ctx.res.body = { 'msg': f'Profile with id {pid} created.'}

Retrieve a profile with GET

@profile_api.get("/profiles/:id")
async def get_profile(ctx: HttpContext) -> None:
  pid = ctx.req.params['id']
  d = await profiles.get(pid)

  ctx.res.body = f"{d.content}"

Remove a profile with DELETE

@profile_api.delete("/profiles/:id")
async def delete_profiles(ctx: HttpContext) -> None:
  pid = ctx.req.params['id']

  try:
    d = await profiles.delete(pid)
    ctx.res.body = { 'msg': f'Profile with id {pid} deleted.'}
  except:
    ctx.res.status = 404
    ctx.res.body = { 'msg': f'Profile with id {pid} not found.'}

Ok, let's run this thing!

Now that you have an API defined with handlers for each of its methods, it's time to test it locally.

nitric start

Once it starts, the application will receive requests via the API port. You can use cURL, Postman or any other HTTP client to test the API.

We will keep it running for our tests. If you want to update your functions, just save them, they'll be reloaded automatically.

Test your API

Update all values in brackets [] and change the URL to your deployed URL if you're testing on the cloud.

Create Profile

curl --location --request POST 'http://localhost:4001/profiles' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "name": "Peter Parker",
    "age": "21",
    "homeTown" : "Queens"
}'

Fetch Profile

curl --location --request GET 'http://localhost:4001/profiles/[id]'

Delete Profile

curl --location --request DELETE 'http://localhost:4001/profiles/[id]'

Deploy to the cloud

At this point, you can deploy what you've built to any of the supported cloud providers. To do this start by setting up your credentials and any configuration for the cloud you prefer:

• AWS
• Azure
• GCP

Next, we'll need to create a stack. A stack represents a deployed instance of an application, which is a collection of resources defined in your project. You might want separate stacks for each environment, such as stacks for dev, test and prod. For now, let's start by creating a dev stack.

nitric stack new

? What should we name this stack? dev
? Which provider do you want to deploy with? aws
? Which region should the stack deploy to? us-east-1

AWS

Note: You are responsible for staying within the limits of the free tier or any costs associated with deployment.

We called our stack dev, let's try deploying it with the up command

nitric up

When the deployment is complete, go to the relevant cloud console and you'll be able to see and interact with your API.

To tear down your application from the cloud, use the down command:

nitric down

Optional - Add profile image upload/download support

If you want to go a bit deeper and create some other resources with Nitric, why not add images to your profiles API.

Access profile buckets with permissions

Define a bucket named profilesImg with reading/writing permissions

photos = bucket("photos").allow('reading','writing')

Add imports for time and date so that we can set up caching/expiry headers

from datetime import datetime, timedelta

Get a URL to upload a profile image

@profile_api.get("/profiles/:id/image/upload")
async def upload_profile_image(ctx: HttpContext) -> None:
  pid = ctx.req.params['id']

  photo =  photos.file(f'images/{pid}/photo.png')
  photo_url = await photo.upload_url(expiry=3600)

  expires = datetime.utcnow() + timedelta(seconds=(3600))
  expires = expires.strftime("%a, %d %b %Y %H:%M:%S GMT")
  ctx.res.headers['Expires'] = expires

  ctx.res.body = photo_url

Get a URL to download a profile image

@profile_api.get("/profiles/:id/image/view")
async def download_profile_image(ctx: HttpContext) -> None:
  pid = ctx.req.params['id']

  photo =  photos.file(f'images/{pid}/photo.png')
  photo_url = await photo.download_url(expiry=3600)

  expires = datetime.utcnow() + timedelta(seconds=(3600))
  expires = expires.strftime("%a, %d %b %Y %H:%M:%S GMT")
  ctx.res.headers['Expires'] = expires

  ctx.res.body = photo_url

You can also directly redirect to the photo URL.

@profile_api.get("/profiles/:id/image/view")
async def download_profile_image(ctx: HttpContext) -> None:
  pid = ctx.req.params['id']

  photo =  photos.file(f'images/{pid}/photo.png')
  photo_url = await photo.download_url(expiry=3600)

  expires = datetime.utcnow() + timedelta(seconds=(3600))
  expires = expires.strftime("%a, %d %b %Y %H:%M:%S GMT")
  ctx.res.headers['Expires'] = expires
  ctx.res.headers['Location'] = [photo_url]
  ctx.res.status = 303

Time to test the updated API

Update all values in brackets [] and change the URL to your deployed URL if you're testing on the cloud.

Get an image upload URL

curl --location --request GET 'http://localhost:4001/profiles/[id]/image/upload'

Using the upload URL with curl

curl --location --request PUT '[url]' \
--header 'content-type: image/png' \
--data-binary '@/home/user/Pictures/photo.png'

Get an image download URL

curl --location --request GET 'http://localhost:4001/profiles/[id]/image/download'

Wrapping Up

In this exploration, we created a Profile Management API using Nitric, handled core profile operations, and extended it for image management.

Nitric proves to be a reliable companion in swiftly moving from idea to a live, cloud-hosted API. Now it's your turn to expand this project or embark on new adventures with Nitric.

Happy coding!

This post originally featured on the Nitric website.