Programmation avec les API Java, partie 1: OpenAPI et Swagger

Pendant que vous preniez votre café, le développement d'applications Java a changé - encore une fois .

Dans un monde propulsé par des changements rapides et des innovations, il est ironique que les API reviennent. Comme l'équivalent de codage du système de métro de New York à l'ère des voitures autonomes, les API sont une technologie ancienne - ancienne mais indispensable. Ce qui est intéressant, c'est comment cette architecture informatique invisible et quotidienne est repensée et utilisée dans les tendances technologiques actuelles.

Bien que les API soient partout, elles sont devenues particulièrement importantes dans leur incarnation à distance en tant que services RESTful, qui sont l'épine dorsale des déploiements dans le cloud. Les services cloud sont des API publiques , caractérisées par des points de terminaison accessibles au public et des structures publiées. Les applications basées sur le cloud évoluent également vers les microservices , qui sont des déploiements indépendants mais liés. Tous ces facteurs augmentent la proéminence des API.

Dans ce didacticiel en deux parties, vous apprendrez à placer les API Java au cœur de votre processus de conception et de développement, du concept au codage. La partie 1 commence par un aperçu et vous présente OpenAPI, également connu sous le nom de Swagger. Dans la partie 2, vous apprendrez à utiliser les définitions d'API de Swagger pour développer une application Spring Web MVC avec une interface Angular 2.

Qu'est-ce qu'une API Java?

Les API sont si courantes dans le développement de logiciels que l'on suppose parfois que les programmeurs savent simplement ce qu'elles sont. Plutôt que de nous fier à l'osmose, prenons une minute pour découvrir ce que nous voulons dire lorsque nous parlons d'API.

En général, nous pouvons dire que les API définissent et gèrent les limites entre les systèmes.

Premièrement, API signifie «interface de programmation d'application». Le rôle d'une API est de spécifier comment les composants logiciels interagissent. Si vous êtes familiarisé avec la programmation orientée objet, vous connaissez les API dans leur incarnation en tant qu'interfaces et classes utilisées pour accéder aux fonctionnalités sous-jacentes du langage, ou en tant que visage public des bibliothèques tierces et des capacités du système d'exploitation.

En général, nous pouvons dire que les API définissent et gèrent les limites entre les systèmes, comme le montre la figure 1.

Matthew Tyson

Alors, où cela nous laisse-t-il avec un développement piloté par API?

API Java pour le cloud computing, les microservices et REST

La programmation avec des API prend le dessus avec l'API Web moderne: une API exposée au réseau (NEA) , où la frontière entre les systèmes est «sur le fil». Ces limites sont déjà centrales pour les applications Web, qui sont le point de contact commun entre les clients frontaux et les serveurs principaux. La révolution du cloud a augmenté de façon exponentielle l'importance des API Java.

Toute activité de programmation qui nécessite la consommation de services cloud (qui sont essentiellement des API publiques) et la déconstruction de systèmes en déploiements plus petits, indépendants mais connexes (également appelés microservices), repose fortement sur les API. Les API exposées au réseau sont simplement plus universelles, plus faciles à obtenir et plus facilement modifiées et étendues que les API traditionnelles. La tendance architecturale actuelle est de capitaliser sur ces caractéristiques.

Les microservices et les API publiques sont issus des racines de l'architecture orientée services (SOA) et des logiciels en tant que service (SaaS). Bien que la SOA soit une tendance depuis de nombreuses années, son adoption généralisée a été entravée par la complexité et les frais généraux de la SOA. L'industrie a opté pour les API RESTful comme norme de facto, offrant juste assez de structure et de convention avec plus de flexibilité dans le monde réel. Avec REST comme toile de fond, nous pouvons créer des définitions d'API formelles qui conservent la lisibilité humaine. Les développeurs créent des outils autour de ces définitions.

En général, REST est une convention pour mapper des ressources sur des chemins HTTP et leurs actions associées. Vous avez probablement vu cela comme des méthodes HTTP GET et POST. L'essentiel est d'utiliser HTTP lui-même comme standard, et de superposer les mappages conventionnels pour la prévisibilité.

Utilisation des API Java dans la conception

Vous pouvez voir l'importance des API, mais comment les utiliseriez-vous à votre avantage?

L'utilisation des définitions d'API Java pour piloter le processus de conception et de développement est un moyen efficace de structurer votre réflexion sur les systèmes informatiques. En utilisant les définitions d'API Java dès le tout début du cycle de vie du développement logiciel (collecte de concepts et d'exigences), vous créerez un artefact technique précieux qui sera utile jusqu'au déploiement, ainsi que pour la maintenance continue.

Voyons comment les définitions d'API Java relient les étapes de conception et de mise en œuvre du développement.

API descriptives vs prescriptives

Il est utile de faire une distinction entre les API descriptives et prescriptives. Une API descriptive décrit la manière dont le code fonctionne réellement, tandis qu'une API prescriptive décrit comment le code doit fonctionner.

Ces deux styles sont utiles et sont tous deux grandement améliorés grâce à l'utilisation d'un format standard structuré pour la définition d'API. En règle générale, l'utilisation de l'API pour piloter la création de code est une utilisation normative, tandis que l'utilisation du code pour générer la définition de l'API Java est une utilisation descriptive.

Collecte des exigences avec les API Java

Du côté du concept à la mise en œuvre, la collecte des exigences est bien terminée. Mais même au stade conceptuel du développement d'applications, nous pouvons commencer à penser en termes d'API.

Supposons que votre système en conception traite des vélos de montagne - construction, pièces, etc. En tant que développeur orienté objet, vous commencez par parler aux parties prenantes des exigences. Assez rapidement après cela, vous penseriez à une BikePartclasse abstraite .

Ensuite, vous penseriez à l'application Web qui gérerait les différents objets de pièces de vélo. Bientôt, vous arriverez à des exigences communes pour gérer ces pièces de vélo. Voici un aperçu de la phase des exigences de la documentation pour une application de pièces de vélo:

  • L'application doit être capable de créer un type de pièce de vélo (levier de vitesses, frein, etc.).
  • Un utilisateur autorisé doit être en mesure de répertorier, créer et activer un type de pièce.
  • Un utilisateur non autorisé doit être en mesure de répertorier les types d'articles actifs et d'afficher les listes d'instances de types d'articles individuels dans le système.

Vous pouvez déjà voir les contours des services prendre forme. En gardant à l'esprit les API éventuelles, vous pouvez commencer à esquisser ces services. À titre d'exemple, voici une liste partielle des services RESTful CRUD pour les types de pièces de vélo:

  • Créer un type de pièce de vélo: PUT /part-type/
  • Mettre à jour le type de pièce de vélo: POST /part-type/
  • Liste des types de pièces: GET /part-type/
  • Obtenez les détails du type de pièce: GET /part-type/:id

Remarquez comment les services CRUD commencent à faire allusion à la forme de diverses limites de service. Si vous créez un style de microservices, vous pouvez déjà voir trois microservices émergeant de la conception:

  • Un service de pièces de vélo
  • Un service de type pièce de vélo
  • Un service d'authentification / autorisation

Because I think of APIs as boundaries of related entities, I consider the microservices from this list to be API surfaces. Together, they offer a big-picture view of the application architecture. Details of the services themselves are also described in a fashion that you will use for the technical specification, which is the next phase of the software development lifecycle.

Technical specification with Java APIs

If you've included the API focus as part of requirements gathering, then you already have a good framework for technical specification. The next stage is selecting the technology stack you will use to implement the specification.

With so much focus on building RESTful APIs, developers have an embarrassment of riches when it comes to implementation. Regardless of the stack you choose, fleshing out the API even further at this stage will increase your understanding of the app's architectural needs. Options might include a VM (virtual machine) to host the application, a database capable of managing the volume and type of data you're serving, and a cloud platform in the case of IaaS or PaaS deployment.

You can use the API to drive "downward" toward schemas (or document structures n NoSQL), or "upward" toward UI elements. As you develop the API specification, you will likely notice an interplay between these concerns. This is all good and part of the process. The API becomes a central, living place to capture these changes.

Another concern to keep in mind is which public APIs your system will expose. Give extra thought and care to these. Along with assisting in the development effort, public APIs serve as the published contract that external systems use to interface with yours.

Public cloud APIs

In general, APIs define the contract of a software system, providing a known and stable interface against which to program other systems. Specifically, a public cloud API is a public contract with other organizations and programmers building systems. Examples are the GitHub and Facebook APIs.

Documenting the Java API

At this stage, you will want to start capturing your APIs in formal syntax. I've listed a few prominent API standards in Table 1.

Comparing API formats

 
Name Summary Stars on GitHub URL
OpenAPI JSON and YML Supported API Standard descended from the Swagger project, includes variety of tools in the Swagger ecosystem. ~6,500 //github.com/OAI/OpenAPI-Specification
RAML YML based spec supported mainly by MuleSoft ~3,000 //github.com/raml-org/raml-spec
API BluePrint An API design language using MarkDown-like syntax ~5,500 //github.com/apiaryio/api-blueprint/

Virtually any format you choose for documenting your API should be okay. Just look for a format that is structured, has a formal spec and good tooling around it, and looks like it will be actively maintained long term. Both RAML and OpenAPI fit that bill. Another neat project is API Blueprint, which uses markdown syntax. For examples in this article we're going to use OpenAPI and Swagger.

OpenAPI and Swagger

OpenAPI is a JSON format for describing REST-based APIs. Swagger started as OpenAPI, but has evolved into a set of tools around the OpenAPI format. The two technologies complement each other well.

Introducing OpenAPI

OpenAPI is currently the most common choice for creating RESTful definitions. A compelling alternative is RAML (RESTful API Markup Language), which is based on YAML. Personally, I've found the tooling in Swagger (especially the visual designer) more polished and error-free than in RAML.

OpenAPI uses JSON syntax, which is familiar to most developers. If you'd rather not strain your eyes parsing JSON, there are UIs to make working with it easier. Part 2 introduces UIs for RESTful definitions.

Listing 1 is a sample of OpenAPI's JSON syntax.

Listing 1. OpenAPI definition for a simple BikePart

 "paths": { "/part-type": { "get": { "description": "Gets all the part-types available in the system", "operationId": "getPartTypes", "produces": [ "application/json" ], "responses": { "200": { "description": "Gets the BikeParts", "schema": { "type": "array", "items": { "$ref": "#/definitions/BikePart" } } } } } } } 

This definition is so concise it is practically Spartan, which is fine for now. There's plenty of room to increase the detail and complexity of the API definition going forward. I'll show you a more detailed iteration of this definition shortly.

Coding from the Java API

Requirements gathering is done and the basic app has been spec'd out, which means you're ready for the fun part---coding! Having a formal Java API definition gives you some distinct advantages. For one thing, you know what endpoints the back-end and front-end developers need to create and code against, respectively. Even if you are a team of one, you'll quickly see the value of an API-driven approach when you begin coding.

Au fur et à mesure que vous développez l'application, vous verrez également l'intérêt d'utiliser des API pour capturer les échanges entre le développement et l'entreprise. L'utilisation d'outils API accélérera à la fois l'application et la documentation des modifications de code.

Des spécifications plus granulaires et un codage réel peuvent nécessiter plus de détails que la définition laconique de la liste 1. De plus, des systèmes plus grands et plus complexes pourraient mériter des capacités évolutives, comme des références de documents. Le listing 2 montre un exemple plus détaillé de l'API BikePart.

Listing 2. Ajout de détails à la définition de l'API BikePart

 "paths": { "/part-type": { "get": { "description": "Gets all the part-types available in the system", "operationId": "getPartTypes", "produces": [ "application/json" ], "parameters": [ { "name": "limit", "in": "query", "description": "maximum number of results to return", "required": false, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "part-type listing", "schema": { "type": "array", "items": { "$ref": "#/definitions/PartType" } } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } } } }