Giter Club home page Giter Club logo

restinterfaces.jl's Introduction

RestInterfaces.jl

Project Status: Active – The project has reached a stable, usable state and is being actively developed.

Overview

This is a lightweight Julia library for implementing basic REST APIs. It was created to provide a means of programming these APIs using interfaces. It sits on-top of the venerable HTTP.jl.

An Example

The following is an example of a small Hello, World! server.

using HTTP
# HttpError-themed exceptions can be found here; these acheive a special synergy
# with the error-handling middleware we're using below
using RestInterfaces.HttpErrors: unprocessable_entity
# As one might have guessed, abstractions over HttpMethods
using RestInterfaces.HttpMethods: Get, Post
# Several pre-made middleware functions can be found here
# This one converts HttpErrors into Http.Responses
using RestInterfaces.Middleware: handle_errors
# Composable routers with minimal pattern-matching facilities
using RestInterfaces.Middleware.Routers: Router, route
# Resource abstractions
using RestInterfaces.Resources
# THE Resource abstraction
using RestInterfaces.Resources: Resource
# Utilities for extracting information from HTTP.Requests
using RestInterfaces.Utils: json_payload, query_parameters

# Mutable state-- a fake backend
name_state = "World"

## `Hello` resource

# Implement the `Resource` interface by subtyping `Resources.Resource` and extending
# `deserialize`, `process`, and `serialize` for an HttpMethod and the
# specialized resource type
struct Hello <: Resource end

# Post

Resources.deserialize(::Post, ::Hello, req) = json_payload(req) |> x -> x[:name]

function Resources.process(::Post, ::Hello, name::String)
  global name_state
  name_state = name
  return nothing
end

Resources.serialize(::Post, ::Hello, ::Nothing) = HTTP.Response(201);

# Get

function Resources.deserialize(::Get, ::Hello, req)
  global name_state
  return query_parameters(req) |> x -> get(x, "name", name_state)
end

function Resources.process(::Get, ::Hello, name::String)
  if name === "Tokyo"
    unprocessable_entity("Cannot greet Tokyo; ignorant of Japanese\n")
  end
  if name === "Tbilisi"
    return "გამარჯობა, თბილისი!"
  end
  return "Hello, $(name)!\n"
end

Resources.serialize(::Get, ::Hello, greeting::String) = HTTP.Response(200, greeting)

## Server

# Extend this method so that the router can match requests to this resource
Resources.path(::Hello) = "/hello"

# Register routes to a router
router = Router(
  "",
  [
    Hello() => Post(), 
    Hello() => Get(),
  ]
)

# Stack middleware and serve on localhost:8081
route(router) |> handle_errors |> HTTP.serve

A client might then see something like...

$ curl -i -X GET "localhost:8081/hello"
HTTP/1.1 200 OK
Transfer-Encoding: chunked

Hello, World!
$ curl -i -X POST --data '{"name":"Boston"}' "localhost:8081/hello"
HTTP/1.1 201 Created
Transfer-Encoding: chunked

$ curl "localhost:8081/hello"
Hello, Boston!
$ curl "localhost:8081/hello?name=Lagos"
Hello, Lagos!
$ curl "localhost:8081/hello?name=Tbilisi"
გამარჯობა, თბილისი!
$ curl -i "localhost:8081/hello?name=Tokyo"
HTTP/1.1 422 Unprocessable Entity
Transfer-Encoding: chunked

422 Unprocessable Entity - Cannot greet Tokyo; ignorant of Japanese
$ curl -i -X DELETE "localhost:8081/hello"
HTTP/1.1 405 Method Not Allowed
Transfer-Encoding: chunked

405 Method Not Allowed - DELETE not allowed for path

Alternatives

  • Mux.jl is a lightweight layer on top of HTTP.jl that can be used to accomplish the same things that RestInterfaces.jl can accomplish. It is more general and more mature than RestInterfaces.jl is, but I am personally not a fan of the callback-style API.

restinterfaces.jl's People

Contributors

extradosages avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar

restinterfaces.jl's Issues

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.