Java APIを使用したプログラミング、パート1:OpenAPIとSwagger

コーヒーを飲んでいる間に、Javaアプリケーションの開発が変わりました

急速な変化と革新によって推進される世界では、APIが復活しているのは皮肉なことです。自動運転車の時代のニューヨーク市の地下鉄システムと同等のコーディングのように、APIは古い技術であり、古代ですが不可欠です。興味深いのは、この目に見えない日常のITアーキテクチャがどのように再構想され、現在のテクノロジートレンドで使用されているかです。

APIはいたるところにありますが、クラウド展開のバックボーンであるRESTfulサービスとして、リモートの化身で特に目立つようになっています。クラウドサービスはパブリックAPIであり、パブリックに面したエンドポイントと公開された構造によって特徴付けられます。クラウドベースのアプリも、独立しているが関連するデプロイメントであるマイクロサービスに向かう傾向にあります。これらすべての要因により、APIの注目度が高まります。

この2部構成のチュートリアルでは、概念からコーディングまで、JavaAPIを設計および開発プロセスの中心に置く方法を学習します。パート1は概要から始まり、Swaggerとしても知られるOpenAPIを紹介します。パート2では、SwaggerのAPI定義を使用して、Angular2フロントエンドを備えたSpringWebMVCアプリを開発する方法を学習します。

Java APIとは何ですか?

APIはソフトウェア開発では非常に一般的であるため、プログラマーはAPIが何であるかを単に知っていると想定されることがあります。浸透に頼るのではなく、APIについて話すときの意味を解き明かしてみましょう。

一般に、APIはシステム間の境界を設定および管理していると言えます。

まず、APIは「アプリケーションプログラミングインターフェイス」の略です。APIの役割は、ソフトウェアコンポーネントがどのように相互作用するかを指定することです。オブジェクト指向プログラミングに精通している場合は、言語の基盤となる機能へのアクセスを取得するために使用されるインターフェイスとクラスとして、またはサードパーティのライブラリとOS機能の公開面としてのAPIをご存知でしょう。

一般に、図1に示すように、APIはシステム間の境界を設定および管理していると言えます。

マシュータイソン

では、それはAPI主導の開発をどこに残すのでしょうか?

クラウドコンピューティング、マイクロサービス、REST用のJava API

APIを使用したプログラミングは、最新のWeb APIであるネットワーク公開API(NEA)で前面に出てきます。この場合、システム間の境界は「ネットワーク上」にあります。これらの境界は、フロントエンドクライアントとバックエンドサーバー間の共通の連絡先であるWebアプリの中心になっています。クラウド革命により、JavaAPIの重要性が飛躍的に高まりました。

クラウドサービス(基本的にはパブリックAPI)を消費し、システムをより小さく、独立しているが関連するデプロイメント(マイクロサービスとも呼ばれます)に分解する必要があるプログラミングアクティビティは、APIに大きく依存しています。ネットワークに公開されたAPIは、従来のAPIよりも単純に普遍的で、入手が容易で、変更や拡張が容易です。現在のアーキテクチャの傾向は、これらの機能を利用することです。

マイクロサービスとパブリックAPIは、サービス指向アーキテクチャ(SOA)とサービスとしてのソフトウェア(SaaS)のルーツから成長しています。SOAは長年のトレンドですが、SOAの複雑さとオーバーヘッドによって、広く採用されることは妨げられてきました。業界は事実上の標準としてRESTfulAPIを採用し、より現実的な柔軟性を備えた十分な構造と規則を提供しています。RESTを背景として、人間の可読性を維持する正式なAPI定義を作成できます。開発者は、これらの定義に基づいてツールを作成します。

一般に、RESTは、リソースをHTTPパスとそれに関連するアクションにマッピングするための規則です。これらはHTTPGETおよびPOSTメソッドとして見たことがあるでしょう。重要なのは、HTTP自体を標準として使用し、その上に従来のマッピングを重ねて予測可能にすることです。

設計でのJavaAPIの使用

APIの重要性を理解できますが、APIをどのように活用しますか?

Java API定義を使用して設計および開発プロセスを推進することは、ITシステムについての考え方を構造化するための効率的な方法です。ソフトウェア開発ライフサイクル(概念と要件の収集)の最初からJava API定義を使用することにより、展開の直前や継続的なメンテナンスに役立つ貴重な技術成果物を作成できます。

JavaAPI定義が開発の概念段階と実装段階をどのように橋渡しするかを考えてみましょう。

記述的APIと規範的API

記述的APIと規範的APIを区別すると便利です。わかりやすいAPIは一方で、コードが実際に機能する方法を説明規範APIは、コードがどのように説明すべき機能します。

これらのスタイルはどちらも便利であり、API定義に構造化された標準形式を使用することで、どちらも大幅に強化されています。経験則として、APIを使用してコードの作成を促進することは規範的な使用法ですが、コードを使用してJavaAPI定義を出力することは記述的な使用法です。

JavaAPIを使用した要件の収集

概念から実装までの範囲では、要件の収集は概念側ではかなり終わっています。しかし、アプリ開発の概念段階でも、APIの観点から考え始めることができます。

設計中のシステムがマウンテンバイク(建設、部品など)を扱っているとします。オブジェクト指向の開発者は、要件について利害関係者と話すことから始めます。その後すぐに、抽象BikePartクラスについて考えることになります。

次に、さまざまな自転車部品オブジェクトを管理するWebアプリケーションについて考えます。すぐに、これらの自転車部品を管理するための一般的な要件に到達します。自転車部品アプリのドキュメントの要件フェーズのスナップショットは次のとおりです。

  • アプリケーションは、ある種の自転車部品(ギアシフター、ブレーキなど)を作成できる必要があります。
  • 許可されたユーザーは、パーツタイプを一覧表示、作成、およびアクティブ化できる必要があります。
  • 許可されていないユーザーは、アクティブなパーツタイプを一覧表示し、システム内の個々のパーツタイプインスタンスのリストを表示できる必要があります。

すでに、サービスの概要が具体化するのを見ることができます。最終的なAPIを念頭に置いて、これらのサービスのスケッチを開始できます。例として、自転車部品タイプのRESTfulCRUDサービスの部分的なリストを次に示します。

  • 自転車パーツタイプを作成します。 PUT /part-type/
  • バイクパーツタイプの更新: POST /part-type/
  • パーツタイプのリスト: GET /part-type/
  • パーツタイプの詳細を取得します。 GET /part-type/:id

CRUDサービスがさまざまなサービス境界の形を示唆し始めていることに注目してください。マイクロサービススタイルで構築している場合は、デザインから3つのマイクロサービスが出現していることがわかります。

  • 自転車部品サービス
  • 自転車パーツタイプのサービス
  • 認証/承認サービス

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.

アプリケーションを構築すると、APIを使用して開発とビジネスの間のやり取りをキャプチャすることの価値もわかります。APIツールを使用すると、コード変更の適用と文書化の両方が高速化されます。

より詳細な仕様と実際のコーディングには、リスト1の簡潔な定義よりも詳細な情報が必要になる場合があります。さらに、より大規模で複雑なシステムは、ドキュメント参照のように拡張可能な機能に値する可能性があります。リスト2は、BikePartAPIのより具体的な例を示しています。

リスト2.BikePartAPI定義への詳細の追加

 "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" } } } }