How to design a set of event log APIs

Brief introduction

The industry has now reached a strong consensus that the API should be designed in the order of the front-end to the back end, focusing on the developer's use of the API. In a thriving business, there is usually a lot of competing products and APIs, and Easy-to-use, well-designed APIs have an advantage in attracting and retaining developers. In addition, new tools are emerging, not only to help developers design APIs in an iterative fashion, but also to help developers learn and use these APIs.

The key factor in API design is "People", which means that API design tools and document formats must be easy for people to read and write, and the API design standards in this period have been emphasizing "people-oriented". API blueprint in this area is an early use of markdown as the format of the product, while the API design of the vast number of developers and business analysts are familiar with this format.

Late last year, Mulesoft released its own RESTful API modeling Language--raml. The language itself is a patented Third-party language, but because of its range of features, the vast API community has a strong interest in it:

The Raml itself is open source, and it has a built-in set of tools and a parser for the common language. Its development has always been under the high attention of an API steering committee and some user experience practitioners, and the development of third-party tools around Raml is also forming its own ecosystem.

Mulesoft first tried to swagger this document format, but then realised that the format standard was more appropriate for documenting an existing API than for a new API designed from scratch. And what they need is a format that supports a concise, language-focused API design approach that RAML is satisfying.

The description of the API is often redundant and easy to duplicate, which hinders its structure, understanding, and use of it. Raml introduces new language features that support structured files, inheritance, and processing of crosscutting concerns. These characteristics are the main points of concern in this paper.

Raml itself does not bring good API design, and the language and its tools do not have any built-in "best practices." As Mulesoft's CTO Uri Sarid says, the Raml goal is "to describe the API in an open, simple and concise specification that captures the structure of the API and encourages model-based design and reuse that will help release the business potential of the API." ”

Raml is not responsible for the implementation of the API, it is only a specification language. There are now only a handful of open source tools that can implement the APIs described by the Raml language. Apikit can turn a RAML specification into a mule ESB stream, and if your Run-time platform uses a mule ESB, that tool can do some work. Jax-rs CodeGen is more widely used because it can turn a RAML specification into Jax-rs Java code. There is no doubt that support for other languages and platforms will determine, to a large extent, whether Raml can succeed in the end.

The purpose of this article is to show you how to use Raml to design a simple, but useful API, and to demonstrate some of the selectivity of Raml. Rather than as a basis for comparison with other API design or description formats, such as API Blueprint, IO docs, or swagger. What is exciting about this is that we now have a viable and competitive ecosystem in the choice of design, and it has the hope of building a consensus on RESTful API design and specifications.

Requirements for API samples

The function of this sample API that we are going to design is to record the event log in a stream to support the online analysis and reporting business. Use log files to save the state and progress of running software, which is probably as long as the computer itself. But as the system becomes more distributed and the load is divided into a large number of systems (perhaps only briefly), the use of files to manage and analyze logs becomes an impossible task. The current popular design pattern is to look at the log as an event stream. As a result, this EventLog API includes some of the following basic requirements:

Allows a third-party application to write an event to a named event stream.

The event itself has a small number of necessary attributes, along with the extensible context attribute.

Supports getting an event stream.

Gets a series of events within a time period.

Gets a list of events that are paginated.

Supports limiting the number of events obtained, with a reasonable default value of 100.

Supports getting an event by ID.

Events are immutable and can neither be deleted nor modified.

The read of the API is public, but the write operation must be protected by a OAuth 2.0 security schema.

Now let's start exploring the Raml to see how to use it to describe an API that satisfies the above requirements.

In this article, we will use the AnyPoint API designer to write Raml. This designer allows us to view interactive documents during the design process and to simulate (mock) the APIs. We will start with a simple specification and then use the more advanced features in Raml to make our specs more dry. The REST API's specifications are sometimes highly repeatable, contain a large number of boilerplate code, and have to be repeated to write their specifications for very close resource information. Raml provides features that can help you avoid or manage this repeatability, including resource types (resourcetype), trait, and instructions contained in files. We will explain these features step-by-step in the process, and at the end of the example we will cover security specifications.

A simple Raml API

You can download the documentation and introductory guide to Raml on the raml.org website, including the complete RAML specification. In the development of this example, I used the AnyPoint API designer, which contains an online Raml editor.

Defining resources

First, the event log API contains two main resources: an event set, which we call an event flow, and each individual event object itself. For the event flow, we need a post method to create a new event in the event stream and a Get method to return the event in the stream. Each independent event can be obtained through the event flow name and event ID. The following snippet shows the corresponding RAML code for this specification:

#%raml 0.8
# Basic starter RAML with two resources and corresponding methods.

Title:eventlog API
version:1.0
baseuri:http://eventlog.example.org/{version}

/streams/{streamname}:
  displayname:a Named Stream
  description:a Stream is A collection of related events. 
A Named Stream has been defined by the user to contain a list of related events. 
Named Streams are created by POSTing the event to a Named Stream.
  Get:
    description:get a list of events in the this stream.

  Post:
    description:create A new event in the this stream.

/streams/{streamname}/{eventid}: Get
  :
    Description:get A particular event by its Id.