===== API ======

The API design tooling.

JSON API, OpenAPI and JSON Schema Working in Harmony
https://blog.apisyouwonthate.com/json-api-openapi-and-json-schema-working-in-harmony-ad4175f4ff84


==== Communication options =====

{{https://s3.eu-central-1.amazonaws.com/alf-digital-wiki-pics/sharex/rNvZHNhbje.png}}

==== IDEA ====

=== Graphql API ===
Get the data by describing it https://graphql.org/


=== HATEOAS API ===
Use links and self describtive API resources, to navigate trhough teh API.




==== Standard ====

=== HAL - Hypermedia api langauge ===

HAL really is just a document format for a hypermedia API, like HTML is for hypertext. It doesn’t tell you how to express your domain model, and doesn’t really tell you how to use HAL to submit changes.


=== JSON:API  ===
Whereas JSON API is almost like an “ORM over HTTP”, HAL does a lot less for you though, so it’s not really an apples-to-apples type of comparison.

HAL really is just a document format for a hypermedia API, like HTML is for hypertext. It doesn’t tell you how to express your domain model, and doesn’t really tell you how to use HAL to submit changes.


==== Schema====

=== JSON Schema ===
?
http://json-schema.org/

=== Swagger / OpenAPI 3.0 ===
Creating the API describtion in SWAGGER, using the API might be the first step to create an API.
It is for sure a good medium to communicate the APIs.
https://editor.swagger.io/


== Swagger Tools for SWAGGER / Open API3.0 (OAS3) ==

The Swagger tools are now separated from the API Specification.
The API Specification is in Open API 3.0.
The tools still support Open API 3.0

|Swagger UI|Visualization of the SWAGGER API|
|Swagger Editor|Creation of the SWAGGER API|

==== Implementation ====



=== Spring HATEOAS ===
The https://spring.io/projects/spring-hateoas
is the API which is capable to generate a clean HATEOAS API
our of some Data Access Objects (DAOs) / Resources.
The requirement is - the ability to map the backend to DAOs.

By exporting the full API
<code>
http://localhost:8095/v2/api-docs?group=full-api
</code>

and importing it via the Swagger Editor in a browser:
http://editor.swagger.io
<code>
Select Paste JSON… from the File menu.
</code>

It can be imported to SWAGGER form


=== Spring Katharsis.io ===
The lib, helping to implement an API, which is conform to Json:API.

  * https://dzone.com/articles/create-a-json-api-rest-service-with-spring-boot-an
  * https://dzone.com/articles/json-api-using-katharsis-amp-spring-boot

  * There are also libs, which generate a JSON:API conform API from Resources and Data Access Objects. E.g. https://dzone.com/articles/json-api-using-katharsis-amp-spring-boot
  * There is a detailed description of the API structure, separated from the implementation: https://jsonapi.org/ It gives me the possibility to design equally structured APIs, even when using different technologies. (Can mix up e.g. serverless implementations with e.g. Spring)
  * There is a JSON Schema, helping to validate our APIs automagically E.g. https://jsonapi-validator.herokuapp.com/



==== Operation ====

=== SAM Framework ===
The AWS SAM framework is capable of deploying the serverless infrastructure on AWS


=== AWS API Gateway ===
On the AWS API Gateway the APIs can be collected, managed, vizualized.

==Import:==
One can Import an API in Swagger
  * as a SWAGGER file in OpenAPI v2.0 or OpenAPI v3.0
  * as a Cloudformation / SAM Framework describtion