Pengaturcaraan dengan Java API, Bahagian 1: OpenAPI dan Swagger

Semasa Anda mendapatkan kopi, pengembangan aplikasi Java berubah - lagi .

Dalam dunia yang didorong oleh perubahan dan inovasi yang pesat, ironinya API membuat kemunculan semula. Seperti pengekodan yang setara dengan sistem kereta bawah tanah New York City pada zaman kereta autonomi, API adalah teknologi lama - bagus tetapi sangat diperlukan. Apa yang menarik adalah bagaimana seni bina IT yang tidak dapat dilihat setiap hari ini dibayangkan semula dan digunakan dalam trend teknologi semasa.

Walaupun API ada di mana-mana, mereka menjadi sangat terkenal dalam penjelmaan jarak jauh mereka sebagai perkhidmatan RESTful, yang merupakan tulang belakang penyebaran awan. Perkhidmatan awan adalah API awam , yang dicirikan oleh titik akhir dan struktur terbitan yang dihadapi orang ramai. Aplikasi berasaskan awan juga cenderung ke arah perkhidmatan mikro , yang merupakan penerapan bebas tetapi berkaitan. Semua faktor ini meningkatkan keunggulan API.

Dalam tutorial dua bahagian ini, anda akan belajar bagaimana meletakkan API Java di tengah proses reka bentuk dan pengembangan anda, dari konsep hingga pengekodan. Bahagian 1 dimulakan dengan gambaran keseluruhan dan memperkenalkan anda kepada OpenAPI, juga dikenal sebagai Swagger. Dalam Bahagian 2, anda akan belajar bagaimana menggunakan definisi API Swagger untuk mengembangkan aplikasi Spring Web MVC dengan frontend Angular 2.

Apa itu Java API?

API begitu biasa dalam pembangunan perisian sehingga kadang-kadang dianggap bahawa pengaturcara hanya mengetahui apa itu. Daripada bergantung pada osmosis, mari luangkan waktu sebentar untuk membongkar apa yang kita maksudkan ketika kita membincangkan API.

Secara umum, kita dapat mengatakan bahawa API menetapkan dan menguruskan batasan antara sistem.

Pertama, API bermaksud "antara muka pengaturcaraan aplikasi." Peranan API adalah untuk menentukan bagaimana komponen perisian berinteraksi. Sekiranya anda biasa dengan pengaturcaraan berorientasikan objek, anda tahu API dalam penjelmaannya sebagai antara muka dan kelas yang digunakan untuk mendapatkan akses ke ciri-ciri bahasa yang mendasari, atau sebagai wajah umum perpustakaan pihak ketiga dan kemampuan OS.

Secara umum, kita dapat mengatakan bahawa API menetapkan dan menguruskan batas antara sistem, seperti yang terlihat pada Gambar 1.

Matthew Tyson

Oleh itu, di manakah hal itu dapat memberi kita pengembangan berdasarkan API?

API Java untuk pengkomputeran awan, perkhidmatan mikro, dan REST

Pengaturcaraan dengan API muncul di hadapan dengan API web moden: API yang terdedah kepada rangkaian (NEA) , di mana batas antara sistem adalah "melalui kabel." Batasan-batasan ini sudah menjadi pusat aplikasi web, yang merupakan titik kontak biasa antara klien depan dan pelayan belakang. Revolusi awan secara eksponensial meningkatkan kepentingan API Java.

Sebarang aktiviti pengaturcaraan yang memerlukan penggunaan perkhidmatan cloud (yang pada dasarnya adalah API awam) dan mendekonstruksi sistem menjadi penyebaran yang lebih kecil, bebas tetapi berkaitan (juga dikenali sebagai perkhidmatan mikro), sangat bergantung pada API. API yang terdedah pada rangkaian hanya lebih universal, lebih mudah diperoleh, dan lebih mudah diubah dan diperluas daripada API tradisional. Trend seni bina semasa adalah memanfaatkan ciri-ciri ini.

Perkhidmatan mikro dan API awam dikembangkan dari akar seni bina berorientasikan perkhidmatan (SOA) dan perisian-sebagai-a-perkhidmatan (SaaS). Walaupun SOA telah menjadi trend selama bertahun-tahun, penerapan secara meluas dihambat oleh kerumitan dan overhead SOA. Industri ini menggunakan API RESTful sebagai standard de facto, menyediakan struktur dan konvensyen yang cukup dengan fleksibiliti dunia nyata. Dengan REST sebagai latar belakang, kami dapat membuat definisi API formal yang mengekalkan kebolehbacaan manusia. Pembangun membuat perkakas di sekitar definisi tersebut.

Secara umum, REST adalah konvensyen untuk memetakan sumber ke jalur HTTP dan tindakan yang berkaitan dengannya. Anda mungkin melihatnya sebagai kaedah HTTP GET dan POST. Yang penting ialah menggunakan HTTP itu sendiri sebagai standard, dan lapisan pemetaan konvensional di atasnya untuk ramalan.

Menggunakan API Java dalam reka bentuk

Anda dapat melihat kepentingan API, tetapi bagaimana anda menggunakannya untuk keuntungan anda?

Menggunakan definisi API Java untuk mendorong proses reka bentuk dan pembangunan adalah cara yang berkesan untuk menyusun pemikiran anda mengenai sistem IT. Dengan menggunakan definisi Java API sejak awal kitaran hayat pengembangan perisian (pengumpulan konsep dan keperluan), anda akan membuat artifak teknikal berharga yang berguna hingga penggunaan, dan juga untuk penyelenggaraan yang berterusan.

Mari kita pertimbangkan bagaimana definisi API Java merapatkan tahap pengembangan konsep dan pelaksanaan.

API deskriptif vs preskriptif

Ini berguna untuk membezakan antara API deskriptif dan preskriptif. A API deskriptif menggambarkan cara kod sebenarnya fungsi, manakala API preskriptif menerangkan bagaimana kod harus berfungsi.

Kedua-dua gaya ini berguna, dan kedua-duanya ditingkatkan dengan menggunakan format standard dan berstruktur untuk definisi API. Sebagai aturan praktis, menggunakan API untuk mendorong pembuatan kod adalah penggunaan preskriptif, sementara menggunakan kod untuk mengeluarkan definisi API Java adalah penggunaan deskriptif.

Keperluan mengumpulkan dengan API Java

Pada spektrum konseptual-ke-implementasi, pengumpulan keperluan sudah berakhir dari sisi konsep. Tetapi walaupun pada tahap konseptual aplikasi dev, kita dapat mulai berfikir dari segi API.

Katakan reka bentuk sistem anda berkaitan dengan basikal gunung - pembinaan, bahagian, dan sebagainya. Sebagai pemaju berorientasikan objek, anda akan memulakan dengan bercakap dengan pihak berkepentingan mengenai keperluan. Cukup cepat selepas itu, anda akan memikirkan BikePartkelas abstrak .

Seterusnya, anda akan memikirkan melalui aplikasi web yang akan menguruskan pelbagai objek bahagian basikal. Tidak lama lagi, anda akan mendapat keperluan bersama untuk menguruskan bahagian basikal tersebut. Berikut adalah gambaran fasa keperluan dokumentasi untuk aplikasi bahagian basikal:

  • Aplikasi mestilah dapat membuat jenis bahagian basikal (gear shifter, brake, etc.).
  • Pengguna yang sah mesti dapat menyenaraikan, membuat, dan menjadikan jenis bahagian aktif.
  • Pengguna yang tidak dibenarkan mesti dapat menyenaraikan jenis bahagian aktif, dan melihat senarai contoh jenis bahagian individu dalam sistem.

Anda sudah dapat melihat garis besar perkhidmatan yang terbentuk. Dengan mempertimbangkan API akhirnya, anda boleh mula membuat sketsa perkhidmatan tersebut. Sebagai contoh, berikut adalah senarai sebahagian perkhidmatan CRUD RESTful untuk jenis bahagian basikal:

  • Buat jenis bahagian basikal: PUT /part-type/
  • Kemas kini jenis bahagian basikal: POST /part-type/
  • Senaraikan jenis bahagian: GET /part-type/
  • Dapatkan perincian jenis bahagian: GET /part-type/:id

Perhatikan bagaimana perkhidmatan CRUD mula menunjukkan bentuk pelbagai sempadan perkhidmatan. Sekiranya anda membina gaya perkhidmatan mikro, anda sudah dapat melihat tiga perkhidmatan mikro muncul dari reka bentuk:

  • Perkhidmatan bahagian basikal
  • Perkhidmatan jenis basikal
  • Perkhidmatan pengesahan / kebenaran

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.

Semasa anda membina aplikasi, anda juga akan melihat nilai menggunakan API untuk menangkap perundingan antara pembangunan dan perniagaan. Menggunakan alat API akan mempercepat penggunaan dan mendokumentasikan perubahan kod.

Spesifikasi yang lebih terperinci dan pengekodan sebenar mungkin memerlukan perincian yang lebih besar daripada definisi yang tersurat dalam Penyenaraian 1. Selain itu, sistem yang lebih besar dan lebih kompleks dapat memperoleh kemampuan yang akan skala, seperti rujukan dokumen. Penyenaraian 2 menunjukkan contoh BikePart API yang lebih lengkap.

Penyenaraian 2. Menambah perincian definisi 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" } } } }