Skip to content
/ site Public

A platform for building stateful API services.

Notifications You must be signed in to change notification settings

juxt-site/site

Repository files navigation

Site (2.0)

badge

With Site, you can build complete API services 100x quicker than by using traditional web frameworks.

Here’s how you use Site:

  • You write an API description, in OpenAPI format.

  • You set up a Site instance, running in on a machine you own, or with your cloud provider.

  • Where necessary, you code some of the operations needed to serve the API.

  • You deploy the API to your Site instance.

Site does the rest, which includes:

  • Serving your API over proper HTTP, with proper method semantics, response codes, headers, conditional requests, caching and much more.

  • Securing your API with OAuth2, with proper registration of clients, integration with authentication providers, declarative access control, scope and much more.

  • Managing your data, provide data consistency guarentees, an audit trail, event logging and bitemporal data access.

You get to design your API exactly as you want it. Site does the rest.

A better way of building APIs

Site is RESTful. Everything in Site is a web resource, with a URI which you can link to. Web security is built in, not an afterthought.

An 'application server' for today’s web and mobile apps

Site is an Application Data Platform, allowing the deployment of Application Programming Interfaces to serve state to applications.

Site offers the following:

  • Bitemporal data storage (via XTDB)

  • User authentication (including OpenID)

  • Flexible access-control (RBAC, ABAC and policy-based)

  • Support for OpenAPI programmable APIs, with an embedded powerful language.

  • A built-in OAuth2 Authorization Server for issuing access tokens

  • Excellent conformance with standards (HTTP, OAuth2, OpenID) to maximise interoperability and minimize lock-in

On top of these features, Site has strong support for data governance. Every state of the database is accessible at any point in time. Every change to the database is auditable, so you can find out who made which change to the data, and when.

OAuth2

Site fully implements the OAuth2 Authorization Framework. Site assumes the roles of a Resource Server and Authorization Server.

Internal Developer Platforms

Site can be adopted as part of an Internal Developer Platform (IDP).

Status

Site 2.0 is not yet ready for evaluation outside of JUXT, and is in the process of maturing. We are developing 'in the open', please treat this repository in that spirit.

The previous 1.0 generation of Site is maintained at https://github.com/juxt/site.

Which types of projects might I use Site for?

  • You want to get started on a project quickly, and there are requirements for the project to serve data securely over an API.

  • You are building an Internal Developer Platform (IDP) and want to provide a solution to your developers to help them speed their development of APIs.

  • You have a dataset that you want to make available to consumers/customers via a secure OAuth2-compliant API, but don’t want to build a system from scratch.

In these cases, JUXT can provide expert guidance, consulting and development resources, if required. Contact [email protected] to schedule an appointment.

Site with Docker

From a terminal, run the following:

docker run --net host ghcr.io/juxt-site/site-server
Tip
You can replace docker with podman

From another terminal:

alias site='docker exec -it $(docker ps -qf ancestor=ghcr.io/juxt-site/site-server) site'

Now initialise Site and follow the instructions:

site init

Request a token

site request-token --client-secret (as instructed)

Continue with the Getting Started Guide.

Documentation

The latest PDF documentation for Site can be found at https://github.com/juxt-site/book/releases/download/latest/Site.pdf. The source code to the documentation is in another repository: https://github.com/juxt-site/book.

Testing

Run the tests with make test if you have make installed, or if not, with clojure -M:test -m kaocha.runner test.

Technical Description

Site is a standards-compliant web server, fulfilling the roles of an OAuth2 resource server and authorization server.

resource server

The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens.

Resources are documents which represent a resource’s identity (URI), configuration and current state (which might be some data, image or other media). Site stores resources in a database.

A resource request is a standard web request to a URI (as part of an API, such as OpenAPI).

Requests contain an access-token, acquired from an authorization server:

authorization server

The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

Currently, the only supported database is JUXT’s immutable XTDB database. XTDB is a good fit for Site, since many of its features (such as document ids and references) map cleanly onto web concepts (such as URIs and links).

Features

Current development is still focussed on the technical feature set, as required to conform to the relevant standards and provide good interoperability.

Resource Server

  • Content Negotiation

  • Conditional Requests

  • Access Control (RBAC, ABAC or policy based)

Authorization Server

  • Client Registration

  • User Authentication (Basic, Login form, OpenID)

  • OAuth2 access token grants

Programming Site

Some types of resource, such as 'operations', may contain Site 'programs' that are executed when required. All resources are stored in the database, including all program code.

Currently, the only available programming language is SCI.

Consulting

Contact [email protected] if you would like help, we can provide professional consulting services for Site and/or XTDB.

License

The MIT License (MIT)

Copyright © 2020-2023 JUXT LTD.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.