Request Types

When designing an API you need to first think about what type of requests and what routes or paths your api would need to function.

For example, if we were to design a weather app we'd probably want a way to lookup weather alerts for a particular state

http://localhost:8080/weather/alerts/{state}

This url can be broken down into several parts

host → http://localhost
port → 8080
route or path → /weather/alerts/{state}
path parameter → {state}

Before we start writing code for we need to answer some questions:

What kind of data manipulation is this route going to perform?
- Are we adding/removing/updating data? (This determines our http method)
Will this endpoint need any inputs?
- If so, will we need to pass them through the path or inside the body of the http request?

This is when knowing the different type of http methods comes in handy.

Common HTTP methods:

POST → when you want to create some data
GET → when you want to get data
PUT → update some data if it already exists or create it
PATCH → when you want to update some data
DELETE → when you want to delete some data

(there are more methods that aren't in this list)

In the HTTP protocol, you can communicate to each path using one (or more) of these "methods".

In reality you can use any of these http methods to do any of those operations. But it's heavily recommended to use the appropriate http method so that people & machines can easily understand your web api.

Now back to our web example. Lets answer those questions:

This endpoint will return alerts from the US National Weather service api
The only input we will need is the state abbreviation

Since we will only be fetching data and not creating/updating/deleting anything, that means we will want to setup a GET route for our api to handle this type of action.

using Oxygen
using HTTP

@get "/weather/alerts/{state}" function(req::HTTP.Request, state::String)
    return HTTP.get("https://api.weather.gov/alerts/active?area=$state")
end

serve()

With our code in place, we can run this code and visit the endpoint in our browser to view the alerts. Try it out yourself by clicking on the link below.

http://127.0.0.1:8080/weather/alerts/NY