Java API를 사용한 프로그래밍, Part 1 : OpenAPI 및 Swagger

커피를 마시는 동안 Java 애플리케이션 개발이 다시 변경 되었습니다 .

급격한 변화와 혁신이 주도하는 세상에서 API가 다시 돌아오고 있다는 것은 아이러니합니다. 자율 주행 차 시대의 뉴욕시 지하철 시스템에 해당하는 코딩과 마찬가지로 API는 오래 되었지만 필수 불가결 한 오래된 기술 입니다. 흥미로운 점은이 보이지 않는 일상적인 IT 아키텍처가 어떻게 재 구상되고 현재 기술 트렌드에 사용되는지입니다.

API는 어디에나 있지만 클라우드 배포의 중추 인 RESTful 서비스로서 원격 화에서 특히 두드러졌습니다. 클라우드 서비스는 공용 API로 , 공용 엔드 포인트와 게시 된 구조가 특징입니다. 클라우드 기반 앱 은 독립적이지만 관련 배포 인 마이크로 서비스로 향하고 있습니다. 이러한 모든 요소는 API의 중요성을 높입니다.

2 부로 구성된이 튜토리얼에서는 개념에서 코딩에 이르기까지 설계 및 개발 프로세스의 중심에 Java API를 배치하는 방법을 배웁니다. 1 부에서는 개요로 시작하여 Swagger라고도하는 OpenAPI를 소개합니다. Part 2에서는 Swagger의 API 정의를 사용하여 Angular 2 프런트 엔드로 Spring Web MVC 앱을 개발하는 방법을 배웁니다.

Java API 란 무엇입니까?

API는 소프트웨어 개발에서 너무나 흔해서 프로그래머가 단순히 그들이 무엇인지 알고 있다고 가정하기도합니다. 삼투에 의존하는 대신 API에 대해 이야기 할 때 의미하는 바를 풀도록 잠시 시간을내어 보겠습니다.

일반적으로 API는 시스템 간의 경계를 설정하고 관리한다고 말할 수 있습니다.

첫째, API 는 "애플리케이션 프로그래밍 인터페이스"를 의미합니다. API의 역할은 소프트웨어 구성 요소가 상호 작용하는 방식을 지정하는 것입니다. 객체 지향 프로그래밍에 익숙하다면 언어의 기본 기능에 대한 액세스를 얻는 데 사용되는 인터페이스 및 클래스 또는 타사 라이브러리 및 OS 기능의 공개 얼굴로 구현 된 API를 알고있을 것입니다.

일반적으로 그림 1과 같이 API가 시스템 간의 경계를 설정하고 관리한다고 말할 수 있습니다.

매튜 타이슨

그렇다면 API 기반 개발은 어디로가는 것일까 요?

클라우드 컴퓨팅, 마이크로 서비스 및 REST를위한 Java API

API를 사용한 프로그래밍은 최신 웹 API 인 네트워크 노출 API (NEA) 를 사용하여 전면에 나타납니다. 여기서 시스템 간의 경계는 "유선"입니다. 이러한 경계는 이미 프런트 엔드 클라이언트와 백 엔드 서버 간의 공통 접점 인 웹 앱의 중심입니다. 클라우드 혁명은 Java API의 중요성을 기하 급수적으로 증가 시켰습니다.

클라우드 서비스 (기본적으로 공용 API)를 사용하고 시스템을 더 작고 독립적이지만 관련 배포 (마이크로 서비스라고도 함)로 분해해야하는 모든 프로그래밍 활동은 API에 크게 의존합니다. 네트워크에 노출 된 API는 기존 API보다 더 보편적이고 쉽게 얻을 수 있으며 쉽게 수정하고 확장 할 수 있습니다. 현재의 아키텍처 트렌드는 이러한 기능을 활용하는 것입니다.

마이크로 서비스 및 공용 API는 SOA (서비스 지향 아키텍처) 및 SaaS (Software-as-a-Service)의 뿌리에서 성장했습니다. SOA는 수년 동안 추세 였지만 SOA의 복잡성과 오버 헤드로 인해 광범위한 채택이 방해를 받아 왔습니다. 업계는 실질적인 표준으로 RESTful API를 사용하여 실제 유연성이 더 높은 구조와 규칙 만 제공합니다. REST를 배경으로 인간의 가독성을 유지하는 공식 API 정의를 만들 수 있습니다. 개발자는 이러한 정의를 중심으로 도구를 만듭니다.

일반적으로 REST는 리소스를 HTTP 경로 및 관련 작업에 매핑하는 규칙입니다. HTTP GET 및 POST 메서드로 보셨을 것입니다. 핵심은 HTTP 자체를 표준으로 사용하고 예측 가능성을 위해 기존 매핑을 계층화하는 것입니다.

디자인에서 Java API 사용

API의 중요성을 알 수 있지만 API를 어떻게 활용 하시겠습니까?

Java API 정의를 사용하여 설계 및 개발 프로세스를 추진하는 것은 IT 시스템에 대한 생각을 구조화하는 효율적인 방법입니다. 소프트웨어 개발 라이프 사이클 (개념 및 요구 사항 수집)의 초기부터 Java API 정의를 사용하면 배포와 지속적인 유지 관리에 유용한 유용한 기술 아티팩트를 만들 수 있습니다.

Java API 정의가 개발의 개념 및 구현 단계를 연결하는 방법을 고려해 보겠습니다.

설명 적 API와 처방 적 API

설명 API와 규범 API를 구분하는 것이 도움이됩니다. 설명 API는 반면, 코드 실제로 방식으로 기능을 설명 규범 API는 코드가 방법을 설명 해야 작동합니다.

이 두 스타일은 모두 유용하며 API 정의를위한 구조화 된 표준 형식을 사용하여 크게 향상되었습니다. 경험상 API를 사용하여 코드 생성을 유도하는 것은 규범 적 사용이며 코드를 사용하여 Java API 정의를 출력하는 것은 설명 적 사용입니다.

Java API로 수집하는 요구 사항

개념-구현 스펙트럼에서 요구 사항 수집은 개념 측면에서 훨씬 끝났습니다. 그러나 앱 개발의 개념적 단계에서도 API 측면에서 생각할 수 있습니다.

Say your system-in-design is dealing with mountain bikes--construction, parts, and so forth. As an object-oriented developer, you'd start by talking to stakeholders about requirements. Pretty quickly after that, you would be thinking about an abstract BikePart class.

Next, you would think through the web application that would manage the various bike parts objects. Soon, you would arrive at common requirements to manage those bike parts. Here's a snapshot of the requirements phase of documentation for a bike parts app:

  • The application must be able to create a type of bike part (gear shifter, brake, etc.).
  • An authorized user must be able to list, create, and make a part type active.
  • An unauthorized user must be able to list active part types, and view lists of individual part-type instances in the system.

Already you can see the outlines of services taking shape. With eventual APIs in mind, you can begin sketching out those services. As an example, here's a partial listing of RESTful CRUD services for bike-part types:

  • Create bike part type: PUT /part-type/
  • Update bike part type: POST /part-type/
  • List part types: GET /part-type/
  • Get part type detail: GET /part-type/:id

Notice how the CRUD services begin to hint at the shape of various service boundaries. If you're building in a microservices style, you can already see three microservices emerging from the design:

  • A bike-part service
  • A bike part-type service
  • An authentication/authorization service

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는 BikePart API의보다 구체화 된 예제를 보여줍니다.

Listing 2. 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" } } } }