An introduction to Pragma

Welcome, we're glad to have you here! This guide is a short introduction to Pragma and its different parts. By the end of it, you should have a good grasp of the goals and fundamentals of Pragma.

What is Pragma?

Pragma is, first and foremost, an opinionated architecture for building RESTful HTTP APIs.

We say it's an architecture because the concepts behind Pragma are not specific to Ruby and can be implemented in any other language.

We say it's opinionated because, while the Ruby implementation provides a lot of room for customization, it is very strongly recommended to stick to the defaults for maximum interoperability. This means that Pragma-based APIs all speak the same language when it comes to operating on and representing resources.

"Pragma" also refers to the canonical Ruby implementation of the Pragma architecture, which sets the de-facto standard for any other implementations. This implementation is comprised of different Ruby gems, each implementing a different component of the architecture, and several supporting gems that provide additional behavior/tooling.

Pragma is NOT a Web framework: in order to work in a real-world environment, it needs an underlying framework to deal with the HTTP layer. With that said, Pragma is framework-agnostic and can be easily integrated with any Web framework.

Pragma supports a variety of use cases: it can be used to build internal APIs, public APIs or even service-oriented architectures. By providing sensible default choices, Pragma allows the developer to focus on the business logic of their API, while abstracting all the little details in an explicit manner (i.e. there is really no magic behind it).

Both the Pragma architecture and its Ruby implementation are based on Trailblazer, a high-level architecture for building highly maintainable Web applications in Ruby. In fact, a lot of the functionality provided by Pragma is nothing more than an extension of Trailblazer's own features. We track Trailblazer closely and try to reuse and contribute back as much as possible and we are extremely thankful to the Trailblazer team for the amazing work they do.

The Pragma ecosystem

As we mentioned, the core of Pragma is split into several components (currently four) which provide the basic functionality for building a RESTful HTTP API. These are:

• Operation: Operations are the basic building block of a Pragma API. An operation represents some action that can be taken on an API resource. Operations interact with the other components to accomplish their job, encapsulating the business logic and dealing with the HTTP request and response.
• Policy: Policies allow you to authorize incoming HTTP requests, controlling who can perform what operations on a given API resource.
• Contract: Contracts deal with parsing, coercing and validating incoming data. They can be employed in a number of different scenarios, validating both GET and POST/PATCH/PUT data, to ensure your code is always dealing with good information.
• Decorator: Decorators convert your domain models to JSON for exposure to external clients. They provide support for pagination, collections, conditional rendering and much more and are easily extensible.

In Pragma, operations, policies, contracts and decorators make up resources. A resource (also called "API resource") represents a domain model in your API (e.g. Article, User, Project) and exposes all the information and behavior an API client needs to interact with the domain model.

These four components can be used separately if you wish, but usually they come wrapped by a main Pragma component which integrates them and also provides highly extensible and customizable default implementations of the five CRUD operations (Index, Show, Create, Update and Delete).

There are more optional components that extend Pragma's behavior with new features, like support for specific Web frameworks, Stripe-style API versioning or the ability to interact with other Pragma APIs. Some of these are stable while others are in active development. We suggest taking a look at the pragmarb GitHub organization for a list of all components.

What's next?

Now that you understand the fundamentals of Pragma, it's time to dive into the code! Move on to Your first Pragma API to build a basic CRUD API with Pragma.