InterSystems IRIS에서 사양 우선 순위를 사용하여 REST API 개발

25862 단어
이 문서에서 REST API 개발의 사양 우선 순위에 대해 살펴보겠습니다.
기존 코드 우선 API 개발은 다음과 같습니다.
  • 코드 작성
  • REST 활성화
  • REST API로 기록
    • Spec first는 같은 단계를 따르지만 그 반대입니다.우리는 규범에서 시작하여 문서로서 템플릿 REST 응용 프로그램을 만들고 마지막으로 업무 논리를 작성합니다.
    이것은 유리하다. 왜냐하면:
  • REST API
    • 를 사용하려는 외부 또는 프런트엔드 개발자에게는 항상 유용한 문서가 있어야 합니다.
  • OAS(Swagger)에서 만든 규범은 각종 도구에 가져올 수 있으며 편집, 클라이언트 생성, API 관리, 단원 테스트와 많은 다른 작업의 자동화 또는 간소화
    • 를 허용한다.
  • 향상된 API 아키텍처코드 우선 방법 중 API는 일종의 방법 일종의 방법으로 개발된 것이기 때문에 개발자는 전체 API 체계 구조에 대한 추적을 잃기 쉽다. 그러나 규범에 따라 첫 번째 개발자는 API 소비자의 위치에서 API와 상호작용을 해야 한다. 이것은 일반적으로 더욱 깨끗한 API 체계 구조를 설계하는 데 도움이 된다
  • 더 빠른 개발 - 모든 샘플 코드가 자동으로 생성되기 때문에 작성할 필요가 없고 업무 논리만 개발하면 됩니다.
  • 신속한 피드백 주기 – 소비자는 API를 즉시 볼 수 있고 규범
    • 만 수정하면 조언을 쉽게 제공할 수 있다.
    규범을 우선시하는 방식으로 API를 개발합시다!
    계획
  • 규범을 거들먹거리며 제정하다
    Docker
  • 로컬
  • 온라인
  • IRIS에 사양 로드
  • API 관리 REST API
  • ^ 나머지
  • 학급
  • 우리 규격이 왜요?
  • 실행
  • 진일보
  • 고려 사항
  • 특수 매개 변수
  • CORS
  • IAM에 사양 로드
    • 규범을 제정하다
    첫 번째 단계는 사양을 작성하는 것입니다. InterSystems IRIS는

    OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:

    • Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)
    • Operation parameters Input and output for each operation
    • Authentication methods
    • Contact information, license, terms of use and other information.

    API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: OpenAPI 3.0 Specification


    Swagger를 사용하여 API를 작성합니다.흔들리는 방법은 다음과 같습니다.
  • Swagger
    • Docker:docker run -d -p 8080:8080 swaggerapi/swagger-editor
  • Online
    • Swigger를 설치/실행하면 웹 브라우저에서 이 창을 볼 수 있습니다.
    Local installation
    왼쪽에서는 API 사양을 편집하고 오른쪽에서는 렌더링된 API 문서/테스트 도구를 즉시 볼 수 있습니다.
    첫 번째 API 사양을 에 로드합니다.이것은 GET 요청 하나만 있는 간단한 API입니다. 지정한 범위의 무작위 수를 되돌려줍니다.
    수학 API 사양
    swagger: "2.0"
info:
  description: "Math"
  version: "1.0.0"
  title: "Math REST API"
host: "localhost:52773"
basePath: "/math"
schemes:
  - http
paths:
  /random/{min}/{max}:
    get:
      x-ISC_CORS: true
      summary: "Get random integer"
      description: "Get random integer between min and max"
      operationId: "getRandom"
      produces:
      - "application/json"
      parameters:
      - name: "min"
        in: "path"
        description: "Minimal Integer"
        required: true
        type: "integer"
        format: "int32"
      - name: "max"
        in: "path"
        description: "Maximal Integer"
        required: true
        type: "integer"
        format: "int32"
      responses:
        200:
          description: "OK"
    다음은 그것의 구성 부분이다.
    API 및 사용된 OAS 버전에 대한 기본 정보
    swagger: "2.0"
info:
  description: "Math"
  version: "1.0.0"
  title: "Math REST API"
    서버 호스트, 프로토콜(http, https) 및 웹 응용 프로그램 이름:
    host: "localhost:52773"
basePath: "/math"
schemes:
  - http
    다음에 경로 (따라서 전체 URL은 YAML) 와 HTTP 요청 방법 (get,post,put,delete) 을 지정합니다.
    paths:
  /random/{min}/{max}:
    get:
    그런 다음 요청에 대한 정보를 지정합니다.
          x-ISC_CORS: true
      summary: "Get random integer"
      description: "Get random integer between min and max"
      operationId: "getRandom"
      produces:
      - "application/json"
      parameters:
      - name: "min"
        in: "path"
        description: "Minimal Integer"
        required: true
        type: "integer"
        format: "int32"
      - name: "max"
        in: "path"
        description: "Maximal Integer"
        required: true
        type: "integer"
        format: "int32"
      responses:
        200:
          description: "OK"
    이 섹션에서는 다음과 같은 요청을 정의합니다.
  • CORS용 경로 설정(나중에 자세히 설명)
  • 요약 및 설명 제공

  • operationId는 규범에서 인용할 수 있으며 우리의 실현 클래스
    • 에서 생성된 방법명입니다

  • 생성-응답 형식(예를 들어 텍스트,xml,json)

  • 매개변수URL에서나 본문에서나 입력 매개변수를 지정합니다. 이 예에서는 임의 생성기
    • 에 대한 매개변수 2개 - 범위를 지정합니다.

  • 응답 가능한 응답 양식 서버 목록
    • 보시다시피 이 격식은 특별히 도전적인 것이 아닙니다. 비록 더 많은 기능을 사용할 수 있지만, 여기에 하나 http://localhost:52773/math/random/:min/:max 가 있습니다.
    마지막으로 정의를 JSON으로 내보냅니다.분류하여 보존하다→ 변환하여 JSON으로 저장합니다.사양은 다음과 같습니다.
    수학 API 사양
    {
  "swagger": "2.0",
  "info": {
    "description": "Math",
    "version": "1.0.0",
    "title": "Math REST API"
  },
  "host": "localhost:52773",
  "basePath": "/math",
  "schemes": [
    "http"
  ],
  "paths": {
    "/random/{min}/{max}": {
      "get": {
        "x-ISC_CORS": true,
        "summary": "Get random integer",
        "description": "Get random integer between min and max",
        "operationId": "getRandom",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "min",
            "in": "path",
            "description": "Minimal Integer",
            "required": true,
            "type": "integer",
            "format": "int32"
          },
          {
            "name": "max",
            "in": "path",
            "description": "Maximal Integer",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}
    IRIS에 사양 로드
    이제 InterSystems IRIS에서 이 REST API에 대한 템플릿 코드를 생성할 수 있는 규범이 생겼습니다.
    이 단계에 들어가려면 세 가지가 필요하다.
  • REST 응용 프로그램 이름: 코드를 생성하는 패키지(예를 들어 수학)
  • JSON 형식의 OAS 규범: 우리는 방금 전 단계
    • 에서 그것을 만들었다
  • WEB 어플리케이션 이름: REST API에 액세스하는 기본 경로(이 경우/math)
    • 세 가지 방법으로 우리의 규범을 사용하여 코드를 생성할 수 있는데, 그것들은 본질적으로 같고, 단지 여러 가지 방법을 제공하여 같은 기능을 방문할 뿐이다
  • 호출^%REST절차(인터랙티브 터미널 세션에서Do ^%REST,specification.
  • 호출%REST클래스Set sc = ##class(%REST.API).CreateApplication(applicationName, spec), 비교환식documentation.
  • API를 사용하여 REST APIdocumentation를 관리합니다.
    • 나는 문서가 필요한 절차를 충분히 묘사했기 때문에 하나만 선택하면 된다고 생각한다.두 개의 주석을 추가합니다.
  • 사례 (1) 및 (2)에서 동적 대상에게 파일 이름이나 URL을 전달할 수 있음
  • 사례(2)와 (3)에서 WEB 프로그램을 만들기 위해 추가 호출을 해야 합니다. set sc = ##class(%SYS.REST).DeployApplication(restApp, webApp, authenticationType). 따라서 저희 사례set sc = ##class(%SYS.REST).DeployApplication("math", "/math")에서%sySecurity include file에서 authenticationType 파라미터의 값을 가져와야 합니다. 관련 항목은 $$$Authe\*, 인증되지 않은 접근 허가증$$$AutheUnauthenticated입니다.생략하면 이 인자는 기본적으로 암호 인증입니다.
    • 우리 규격이 왜 그래?
    응용 프로그램을 성공적으로 작성한 경우 세 가지 클래스가 포함된 새 수학 패키지를 작성해야 합니다.

  • 사양 - 기존 스토리지 사양에 따릅니다.

  • Disp - REST 서비스를 호출할 때 직접 호출합니다.그것은 REST 처리를 포장하고 실현 방법을 호출한다.

  • Impl - REST 서비스의 실제 내부 구현을 저장합니다.너는 반드시 이런 종류만 편집해야 한다.
    • documentation 수업에 대한 자세한 내용을 제공합니다.
    구현
    처음에 우리의 실시 과정은 수학이었다.impl에는 우리의/random/{min}/{max} 작업에 대응하는 방법만 포함되어 있습니다.
    /// Get random integer between min and max<br/>
/// The method arguments hold values for:<br/>
///     min, Minimal Integer<br/>
///     max, Maximal Integer<br/>
ClassMethod getRandom(min As %Integer, max As %Integer) As %DynamicObject
{
    //(Place business logic here)
    //Do ..%SetStatusCode(<HTTP_status_code>)
    //Do ..%SetHeader(<name>,<value>)
    //Quit (Place response here) ; response may be a string, stream or dynamic object
}
    간단한 구현부터 시작하겠습니다.
    ClassMethod getRandom(min As %Integer, max As %Integer) As %DynamicObject
{
    quit {"value":($random(max-min)+min)}
}
    마지막으로 브라우저에서 이 페이지를 열어 REST API: Documentation를 호출할 수 있습니다.
    출력은 다음과 같아야 합니다.
    {
    "value": 45
}
    또한 Swagger editor에서 Try it out 버튼을 누르고 요청 매개 변수를 입력하면 같은 요청이 전송됩니다.
    http://localhost:52773/math/random/1/100
    축하합니다!우리가 규범에 우선하는 방법으로 만든 첫 번째 REST API가 지금 출시되었습니다!
    한층 더 발전하다.
    물론 저희 API는 정적이 아닙니다. 새로운 경로를 추가해야 합니다.spec first 개발에서 먼저 규범을 수정한 다음에 REST 프로그램을 업데이트하고 마지막으로 코드를 작성합니다.규범 업데이트는 안전합니다. 코드는 영향을 받지 않습니다. 경로가 규범에서 삭제되었더라도 실현 클래스에서 이 방법은 삭제되지 않습니다.
    고려 요소
    추가 참고 사항!
    특수 매개 변수
    InterSystems는 다음과 같이 swagger 사양명세에 특수 매개변수를 추가합니다.
    성함
    자료형태
    약속을 어기다
    장소.
    묘사
    x-ISC_DispatchParent
    클래스 이름
    %CSP.쉬다
    메시지
    스케줄러 클래스
    x-ISC_CORS
    부울 값
    거짓
    조작하다
    이 끝점/메서드 조합을 지원해야 하는 CORS 요청을 나타내는 플래그입니다.
    x-ISC 필수 리소스
    어레이
    조작하다
    REST 서비스에 접근하는 이 노드에 필요한 정의된 자원과 접근 모드 (resource: mode) 의 쉼표 구분 목록입니다.예: [%Development:USE]]
    x-ISC 서비스 접근 방식
    꿰미
    조작하다
    백엔드에서 이 조작에 서비스를 제공하는 클래스 방법의 이름을 호출합니다.기본값은 operationId이며 일반적으로 적합합니다.
    콜스
    CORS 지원을 활성화하는 세 가지 방법이 있습니다.
  • 통과x-ISC\_CORS를 진으로 지정해 노선을 기반으로 한다.이것이 Math REST API에서 수행한 작업입니다.
  • API에 따라 추가
    • Parameter HandleCorsRequest = 1;
    교과 과정을 재편성하다.그것도 규범이 갱신된 후에 살아남을 수 있다.
  • (추천)는 맞춤형 디스패치 슈퍼클래스(확장%CSP.REST를 실현하고 그곳에서 CORS 처리 논리를 작성하여 모든 API를 기반으로 한다.이 슈퍼클래스를 사용하려면 x-ISC\_DispatchParent 규범에 추가하십시오.
    • IAM에 사양 로드
    마지막으로 다른 개발자에게 배포할 수 있도록 IAM에 사양을 추가합니다.
    IAM을 아직 시작하지 않은 경우 를 참조하십시오.REST API는 IAM을 통해 제공되므로 여기서 설명하지 않습니다.InterSystems IRIS 인스턴스가 아닌 IAM을 가리키도록 spec host 및 basepath 매개변수를 수정해야 할 수도 있습니다.
    IAM 관리자 포털을 열고 관련 작업공간의 사양 탭으로 이동합니다.
    this article
    AddSpec 버튼을 클릭하고 새 API의 이름을 입력합니다(예: 수학).IAM에서 새 사양을 작성한 후 를 클릭하여 사양 코드를 편집하고 붙여넣습니다(JSON 또는 YAML - IAM에는 중요하지 않습니다).

    클릭 잊지 마세요Update File.
    현재 우리의 API는 개발자를 위해 발표된 것이다.개발자 포털을 열고 오른쪽 상단에 있는 문서를 클릭하세요.세 가지 기본 API 외에 새로운 Math REST API를 제공해야 합니다.

    열기:

    이제 개발자는 우리의 새로운 API 문서를 보고 같은 곳에서 시도할 수 있습니다!
    결론
    InterSystems IRIS는 REST API의 개발 과정을 간소화하고 spec first 방법은 REST API의 생명 주기를 더욱 빠르고 쉽게 관리할 수 있도록 한다.이 방법을 사용하면 클라이언트 생성, 셀 테스트, API 관리 및 기타 많은 작업과 관련된 다양한 작업을 수행할 수 있습니다.
    링크
  • OpenAPI 3.0 Specification
  • Creating REST Services
  • Starting with IAM
    • 초보자에게 추천하는 고릴라제 도구
    "/bin/bash의 -it"container idor container name

    좋은 웹페이지 즐겨찾기

    개발자 우수 사이트 수집

    개발자가 알아야 할 필수 사이트 100선 추천 우리는 당신을 위해 100개의 자주 사용하는 개발자 학습 사이트를 정리했습니다
    best100-homepage