Pemrograman dengan Java API, Bagian 1: OpenAPI dan Swagger

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

Di dunia yang didorong oleh perubahan dan inovasi yang cepat, sungguh ironis bahwa API kembali populer. Seperti pengkodean yang setara dengan sistem kereta bawah tanah Kota New York di era mobil otonom, API adalah teknologi lama --canggih tetapi sangat diperlukan. Yang menarik adalah bagaimana arsitektur TI sehari-hari yang tak terlihat ini direvisi dan digunakan dalam tren teknologi saat ini.

Meskipun API ada di mana-mana, mereka menjadi sangat menonjol dalam inkarnasi jarak jauhnya sebagai layanan RESTful, yang merupakan tulang punggung penerapan cloud. Layanan cloud adalah API publik , yang dicirikan oleh titik akhir yang dihadapi publik dan struktur yang dipublikasikan. Aplikasi berbasis cloud juga cenderung menuju layanan mikro , yang independen tetapi terkait penerapan. Semua faktor ini meningkatkan keunggulan API.

Dalam tutorial dua bagian ini, Anda akan belajar bagaimana menempatkan Java API di jantung proses desain dan pengembangan Anda, dari konsep hingga pengkodean. Bagian 1 dimulai dengan gambaran umum dan memperkenalkan Anda pada OpenAPI, yang juga dikenal sebagai Swagger. Di Bagian 2, Anda akan mempelajari cara menggunakan definisi API Swagger untuk mengembangkan aplikasi MVC Spring Web dengan frontend Angular 2.

Apa itu Java API?

API sangat umum dalam pengembangan perangkat lunak sehingga terkadang diasumsikan bahwa programmer tahu apa itu. Daripada mengandalkan osmosis, mari luangkan waktu sejenak untuk mengungkap apa yang kita maksud saat kita berbicara tentang API.

Secara umum, kita dapat mengatakan bahwa API mengatur dan mengelola batasan antar sistem.

Pertama, API adalah singkatan dari "antarmuka pemrograman aplikasi". Peran API adalah untuk menentukan bagaimana komponen perangkat lunak berinteraksi. Jika Anda terbiasa dengan pemrograman berorientasi objek, Anda tahu API dalam inkarnasinya sebagai antarmuka dan kelas yang digunakan untuk mendapatkan akses ke fitur dasar bahasa, atau sebagai wajah publik dari pustaka pihak ketiga dan kemampuan OS.

Secara umum, kita dapat mengatakan bahwa API menetapkan dan mengelola batas antar sistem, seperti yang terlihat pada Gambar 1.

Matthew Tyson

Jadi, apa yang meninggalkan kita dengan pengembangan berbasis API?

Java API untuk komputasi awan, layanan mikro, dan REST

Pemrograman dengan API muncul ke depan dengan API web modern: API yang terpapar jaringan (NEA) , di mana batas antara sistem "melewati kabel". Batasan ini sudah menjadi pusat aplikasi web, yang merupakan titik kontak umum antara klien front-end dan server back-end. Revolusi cloud telah secara eksponensial meningkatkan pentingnya Java API.

Setiap aktivitas pemrograman yang memerlukan penggunaan layanan cloud (yang pada dasarnya adalah API publik) dan mendekonstruksi sistem menjadi penerapan yang lebih kecil, independen tetapi terkait (juga dikenal sebagai layanan mikro), sangat bergantung pada API. API yang terpapar jaringan lebih universal, lebih mudah diperoleh, dan lebih mudah dimodifikasi dan diperluas daripada API tradisional. Tren arsitektur saat ini memanfaatkan fitur-fitur ini.

Layanan mikro dan API publik dikembangkan dari akar arsitektur berorientasi layanan (SOA) dan perangkat lunak sebagai layanan (SaaS). Meskipun SOA telah menjadi tren selama bertahun-tahun, adopsi yang luas telah terhambat oleh kompleksitas dan overhead SOA. Industri telah menetapkan RESTful API sebagai standar de facto, menyediakan struktur dan konvensi yang cukup dengan fleksibilitas dunia nyata. Dengan REST sebagai latar belakang, kita dapat membuat definisi API formal yang mempertahankan keterbacaan manusia. Pengembang membuat perkakas seputar definisi tersebut.

Secara umum, REST adalah konvensi untuk memetakan resource ke jalur HTTP dan tindakan terkaitnya. Anda mungkin pernah melihat ini sebagai metode HTTP GET dan POST. Kuncinya adalah menggunakan HTTP itu sendiri sebagai standar, dan lapisan pemetaan konvensional di atasnya untuk prediktabilitas.

Menggunakan API Java dalam desain

Anda dapat melihat pentingnya API, tetapi bagaimana Anda akan menggunakannya untuk keuntungan Anda?

Menggunakan definisi Java API untuk mendorong proses desain dan pengembangan adalah cara yang efisien untuk menyusun pemikiran Anda tentang sistem TI. Dengan menggunakan definisi Java API dari awal siklus pengembangan perangkat lunak (pengumpulan konsep dan persyaratan), Anda akan membuat artefak teknis berharga yang berguna hingga penerapan, serta untuk pemeliharaan berkelanjutan.

Mari kita pertimbangkan bagaimana definisi Java API menjembatani tahap konseptual dan implementasi dari pengembangan.

API deskriptif vs preskriptif

Sangat membantu untuk membuat perbedaan antara API deskriptif dan preskriptif. Sebuah API deskriptif menggambarkan cara kode sebenarnya fungsi, sedangkan API preskriptif menggambarkan bagaimana kode harus berfungsi.

Kedua gaya ini berguna, dan keduanya sangat ditingkatkan dengan menggunakan format standar terstruktur untuk definisi API. Sebagai aturan praktis, menggunakan API untuk mendorong pembuatan kode adalah penggunaan preskriptif, sementara menggunakan kode untuk menghasilkan keluaran, definisi Java API adalah penggunaan deskriptif.

Pengumpulan persyaratan dengan Java API

Pada spektrum konseptual-hingga-implementasi, pengumpulan persyaratan jauh dari sisi konsep. Tetapi bahkan dalam tahap konseptual pengembang aplikasi, kita dapat mulai berpikir dalam kerangka API.

Katakanlah system-in-design Anda menangani sepeda gunung - konstruksi, suku cadang, dan sebagainya. Sebagai pengembang berorientasi objek, Anda akan mulai dengan berbicara dengan pemangku kepentingan tentang persyaratan. Cukup cepat setelah itu, Anda akan berpikir tentang BikePartkelas abstrak .

Selanjutnya, Anda akan berpikir melalui aplikasi web yang akan mengelola berbagai objek suku cadang sepeda. Segera, Anda akan sampai pada persyaratan umum untuk mengelola suku cadang sepeda tersebut. Berikut adalah cuplikan dari fase persyaratan dokumentasi untuk aplikasi suku cadang sepeda:

  • Aplikasinya harus bisa membuat tipe part sepeda (perpindahan gigi, rem, dll).
  • Pengguna yang berwenang harus dapat membuat daftar, membuat, dan mengaktifkan jenis bagian.
  • Pengguna yang tidak sah harus dapat membuat daftar jenis bagian yang aktif, dan melihat daftar contoh jenis bagian dalam sistem.

Anda sudah dapat melihat garis besar layanan mulai terbentuk. Dengan memikirkan API akhirnya, Anda dapat mulai membuat sketsa layanan tersebut. Sebagai contoh, berikut ini sebagian daftar layanan CRUD RESTful untuk jenis bagian sepeda:

  • Buat jenis bagian sepeda: PUT /part-type/
  • Perbarui jenis bagian sepeda: POST /part-type/
  • Buat daftar jenis bagian: GET /part-type/
  • Dapatkan detail jenis bagian: GET /part-type/:id

Perhatikan bagaimana layanan CRUD mulai memberi petunjuk pada bentuk berbagai batasan layanan. Jika Anda membangun dengan gaya layanan mikro, Anda sudah dapat melihat tiga layanan mikro muncul dari desain:

  • Layanan suku cadang sepeda
  • Layanan tipe suku cadang sepeda
  • Layanan otentikasi / otorisasi

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.

Saat Anda membangun aplikasi, Anda juga akan melihat nilai menggunakan API untuk menangkap negosiasi bolak-balik antara pengembangan dan bisnis. Menggunakan alat API akan mempercepat penerapan dan pendokumentasian perubahan kode.

Spesifikasi yang lebih terperinci dan pengkodean yang sebenarnya mungkin memerlukan detail yang lebih besar daripada definisi singkat dalam Daftar 1. Selain itu, sistem yang lebih besar dan lebih kompleks dapat memperoleh kemampuan yang akan diskalakan, seperti referensi dokumen. Daftar 2 menunjukkan contoh yang lebih lengkap dari BikePart API.

Kode 2. Menambahkan detail ke definisi BikePart API

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