search

amadeus4dev / amadeus-node

Node library for the Amadeus Self-Service travel APIs
https://developers.amadeus.com
MIT License
191 stars 66 forks source link

Checklist #1

Closed cbetta closed 6 years ago

cbetta commented 6 years ago

Amadeus SDK Specification Document

Table of Content | Templates

Status

Overview

The goal of this document is to set a shared standard for implementation and development of all Amadeus SDKs. For the sake of this document, there is no differentiation between SDKs and API client SDKs.

This document is a work in progress, and should be changed and updated as changes are made to the APIs or developer needs are discovered.

Requirement Prioritization

The following document follows the MoSCoW method of prioritising rules. Please follow the following guidelines when evaluating rules.

We do not use the fourth won't level in this specification.

Limitations

Currently this specification is limited due to various reasons. This means that currently:

Table of Contents

Maintenance Requirements

1. Source Control

2. Releases & Versioning

3. CI Server

Additional Content Requirements

4. Documentation

Templates for a lot of these files have been provided in the templates folder

5. Testing

6. Linting

Dependencies & Infrastructure Requirements

7. Dependencies

8. HTTP Client

9. Logging

10. Reporting

Initialization & Interaction Requirements

11. Initialization

12. Namespacing

13. Method Syntax

14. Error Handling

API Mapping Requirements

15. API Calls

16. Responses

17. Requests

18. Pagination

Key Developer Experience Interactions

19. Successful Path Interactions

20. Unsuccessful Path Interactions

amadeus.get('/foo/bar')
W, [2018-02-19T16:06:29.881202 #67814]  WARN -- Amadeus AuthenticationError: {
  "error": "invalid_client",
  "error_description": "Client credentials are invalid",
  "code": 38187,
  "title": "Invalid parameters"
}

Node example: ```js amadeus.client.get('/foo/bar').then(...).catch(...); ``` ```js Amadeus AuthenticationError { error: 'invalid_client', error_description: 'Client credentials are invalid', code: 38187, title: 'Invalid parameters' } ```

- [x] __20.2__ When an unknown path is provided, the error returned __should__ be clear even when debug mode is off
Ruby example: ```ruby amadeus.get('/foo/bar') ``` ```js W, [2018-02-19T16:06:13.523516 #67786] WARN -- Amadeus NotFoundError: [ { "code": 38196, "title": "Resource not found", "detail": "The targeted resource doesn't exist", "status": 404 } ] ```
Node example: ```js amadeus.client.get('/foo/bar').then(...).catch(...); ``` ```js Amadeus NotFoundError [ { code: 38196, title: 'Resource not found', detail: 'The targeted resource doesn\'t exist', status: 404 } ] ```

- [x] __20.3__ When incorrect params are provided, the error returned __should__ be clear even when debug mode is off
Ruby example: ```ruby amadeus.reference_data.locations.get( subType: Amadeus::Location::ANY ) ``` ```js W, [2018-02-19T16:05:55.923870 #67772] WARN -- Amadeus ClientError: [ { "status": 400, "code": 32171, "title": "MANDATORY DATA MISSING", "detail": "Missing mandatory query parameter", "source": { "parameter": "keyword" } } ] ```
Node example: ```js amadeus.referenceData.locations.get({ keyword: 'lon' }).then(...).catch(...); ``` ```js Amadeus ClientError [ { status: 400, code: 32171, title: 'MANDATORY DATA MISSING', detail: 'Missing mandatory query parameter', source: { parameter: 'subType' } } ] ```

- [x] __20.4__ When a server error occurs, the error returned __should__ be clear even when debug mode is off
Ruby example: ```js amadeus.get('/something/that/errors/'); ``` ```js W, [2018-02-19T16:07:42.651272 #67846] WARN -- Amadeus ServerError: [ { "code": 38189, "title": "Internal error", "detail": "An internal error occured, please contact your administrator", "status": 500 } ] ```
Node example: ```js amadeus.get('/something/that/errors/').then(...).catch(...); ``` ```js Amadeus ServerError [ { code: 38189, title: 'Internal error', detail: 'An internal error occured, please contact your administrator', status: 500 } ] ```

- [x] __20.5__ When a network error occurs, the error returned __should__ be clear even when debug mode is off
Ruby example: ```js amadeus.get('/something/that/errors/'); ``` ```js W, [2018-02-19T16:13:14.374444 #68060] WARN -- Amadeus NetworkError: nil ```
Node example: ```js amadeus.get('/something/that/errors/').then(...).catch(...); ``` ```js Amadeus NetworkError null ```

- [x] __20.6__ When a rate limit occurs, the error returned __should__ be clear even when debug mode is off
Ruby example: ```js amadeus.get('/something/that/rate/limits/'); ``` ```js W, [2018-02-19T16:07:42.651272 #67846] WARN -- Amadeus ServerError: [ { code: 38194, title: 'Too many requests', detail: 'The network rate limit is exceeded, please try again later', status: 429 } ] ```
Node example: ```js amadeus.get('/something/that/errors/').then(...).catch(...); ``` ```js Amadeus ClientError [ { code: 38194, title: 'Too many requests', detail: 'The network rate limit is exceeded, please try again later', status: 429 } ] ```

## Specific Language Requirements ### 22. Node / Javascript - [x] __22.1__ The SDK __should__ promises - [x] __22.2__ The SDK __could__ support ES7's `async/await` - [x] __22.3__ The SDK __should__ be written in ES6+ - [x] __22.4__ The SDK __should__ work in an ES5 environment - [x] __22.5__ The SDK __should__ support ES6 modules
cbetta commented 6 years ago

Some notes:

Dependencies

Due to the limitations of the standard libraries in Node, 2 libraries were used as runtime dependencies:

Node 4 compatibility

This library has backwards compatibility support for Node 4, but it is not automatically tested for Node 4 as the testing library used (Jest) does not support Node 4 fully. As the LTS for Node 4 ends this April I don't want to change the testing library just to support Node 4.

CI Server & Deployment

Not set up yet, as we need to make the repo public first

Docs

For now we have included the docs in the repo, so that we can host them temporarily using Github: https://workbetta.github.io/amadeus-node/