OpenAPI - Part 2

Pendahuluan mengenai Dokumentasi API, silahkan lihat di sini

Dari artikel sebelumnya kita tahu bahwa kita perlu spesifikasi dokumentasi API yang :

mempunyai terminologi dokumentasinya yang dipahami oleh hampir semua orang yang terlibat.
dokumentasinya jelas, lengkap dan terstruktur.
harus mudah juga diubah dokumentasinya ketika terjadi perubahan API nya.
untuk tahapan lebih lanjut, mesti bisa digunakan juga untuk validasi API, integrasi API secara otomatis.

OpenAPI mencoba untuk mengakomodasi kebutuhan tersebut.

OpenAPI merupakan spesifikasi, jadi implementasinya bisa bermacam-macam.

OpenAPI ini juga merupakan salah satu dari The Linux Foundation Collaborative Project.

Yaitu project-project Open Source yang dinaungi oleh The Linux Foundation, biasanya project-project bersama yang disponsori oleh perusahaan-perusahaan besar dalam rangka membuat standar teknologi Open Source yang digunakan bersama.

Contohnya juga yang dinaungi oleh The Linux Foundation, misalnya Kubernetes, dan Node.js.

Kita bisa lihat di website offisialnya di : https://www.openapis.org.

dan mengenai The Linux Foundation sendiri di : https://www.linuxfoundation.org

Siapa saja perusahaan yang berada dibalik standarisasi OpenAPI ini ?

Ada beberapa perusahaan besar yang menjadi bagian dari group ini, misalnya :

SmartBear
3scale
Apigee
Google
IBM
Intuit
Microsoft
Paypal
MuleSoft, sebelumnya salah satu kontributor dari spesifikasi API yang lain yaitu RAML
dll

Perusahan-perusahaan diatas ikut bergabung di OpenAPI initiative diatas.

Diawali oleh SmartBear yang sebelumnya mempunyai spesifikasi Swagger.

Implementasinya seperti apa ?

OpenAPI adalah sebuah spesifikasi, jadi pasti ada benda lain yang merupakan implementasinya.

Bentuknya biasanya dalam bentuk tools, library, parser, validator, converter, modeller, dll.

Misalnya :

springdoc-openapi , yaitu library OpenAPI untuk spring-boot.
oasdiff, tools OpenAPI untuk bahasa Golang.
swagger-parser, tools converter untuk OpenAPI.
swagger-api, tools pemodelan untuk Java POJO OpenAPI.
openapi3-ts, library OpenAPI untuk typescript.
swagger-ui, yaitu antarmuka web untuk menampilkan dan melakukan testing OpenAPI.
dll

List lengkapnya bisa dilihat di sini

Apa sebenarnya spesifikasi OpenAPI ini ?

OpenAPI adalah spesifikasi mengenai bagaimana seharusnya REST API (Application Programming Interface) dideskripsikan dalam format yang standar dan mudah dimengerti, baik oleh manusia atau mesin.

Dengan OpenAPI, maka kita bisa tahu bagaimana seharusnya kita mendokumentasikan REST API yang kita punya agar mudah dipahami orang lain, tanpa perlu orang lain melihat lebih dalam code kita, atau tanya lisensi API kita sejauh mana, dll.

Didalamnya terdapat :

informasi mengenai service yang disediakan oleh REST API.
bagaimana cara menggunakan beberapa endpoint URL dan parameternya.
dll

Jadi fokusnya adalah kepada penggambaran REST API yang lengkap dan standar sehingga mudah dimengerti baik oleh kita manusia atau oleh program lainnya.

Pakai apa penggambarannya ?

Penggambarannya tentu saja dengan menggunakan struktur data tertentu yang diadopsi dan dipahami luas di dunia software.

Pilihannya jatuh ke JSON atau YAML

Sebuah struktur data dalam bentuk yang sederhana, dan menyimpan data dalam bentuk key value, dan sekarang sepertinya menjadi standar defacto sebagai Data Transfer Object.

Contohnya bisa kita lihat contohnya (yang memakai JSON) :

{
  "openapi": "3.1.0",
  "info": {
    "title": "Non-oAuth Scopes example",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "security": [
          {
            "bearerAuth": [
              "read:users",
              "public"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "jwt",
        "description": "note: non-oauth scopes are not defined at the securityScheme level"
      }
    }
  }
}

diambil dari sini

Dengan adanya dokumentasi API ini, maka Software Engineer dapat mengerti dengan cepat dan mudah cara penggunaan REST API, dan mengintegrasikannya dengan program mereka tanpa perlu melihat lebih dalam ke level coding.

Apa masalahnya kalau tidak memakai standard OpenAPI ini atau yang semirip ?

Ok, kita coba gali contohnya :

Misalnya kita butuh integrasi dengan sebuah REST API yang menyediakan service pencarian mobil.

Pencarian mobil ini bisa berdasarkan merk mobil, jenis mobil, tahun mobil, dll.

Kemudian kita bisa saja dikasih url di environment development spt ini :

http://xxx.com/dev/mobil?searchKey=<search_merk_jenis_mobil>

Ketika kita test, maka ada response : not authorized

Maka akan ada pertanyaan awal :

apakah perlu otentikasi dan otorisasi dalam bentuk token, dalam bentuk apa ? ditaruh di header atau di parameter url ?
kepada siapa kita perlu hubungi kalau ada pertanyaan seperti ini ?
ada contoh request data beserta otentikasi nya nggak ?
dll.

Pertanyaan dasar tersebut jawabannya simple, yaitu lihat saja di dokumentasinya.

Dokumentasinya bisa dalam bentuk file .txt , .README, .doc , .ppt kalau bentuk presentasi.

Tapi semuanya tidak seragam.

Akhirnya kita coba test dan berhasil, dan kemudian kita memutuskan untuk menggunakannya di Production.

Hmm, tapi tunggu dulu.

Agar bisa dites di production, maka kita perlu memastikan :

apa url REST API untuk production nya ?
API ini menggunakan lisensi jenis apa ?
apa parameter yang wajib, opsional, dan ditaruh dimana saja, path variable, query param, atau di header ?
dll

Banyak sekali pertanyaan-pertanyaan tambahan yang biasanya menjadi standar pertanyaan kita ketika mencoba untuk mengakomodasi integrasi API yang kita butuhkan.

Dan seperti yang kita bicarakan di part1, maka dokumentasi yang ditulis terpisah dengan code nya sendiri, atau digenerate secara manual akan menimbulkan masalah waktu dan informasi yang tidak sinkron.

Standar OpenAPI lagi-lagi berupaya untuk memperbaiki hal tersebut.

Dengan spesifikasi yang dijadikan standar dalam penmbuatan dan pemodelan API kita.

Dengan spesikasi yang lengkap ini , maka akan mudah digenerate dokumen API, ataupun kerangka program client dan server.

Kita lanjut ke next artikel.

Huzefril