search

nodeshift / nodejs-reference-architecture

The Red Hat and IBM Node.js Reference architecture. The teams 'opinion' on what components our customers and internal teams should use when building Node.js applications and guidance for how to be successful in production with those components.
https://nodeshift.dev/nodejs-reference-architecture/
Apache License 2.0
1.66k stars 120 forks source link

First draft of API definition #73

Closed mhdawson closed 2 years ago

mhdawson commented 2 years ago

@InfoSec812 I'm wondering if it might make sense for you to work on this with @wtrocki. It would be a good place to get something related to the API first approach covered.

InfoSec812 commented 2 years ago

I have 2 different API Contracts that I usually use for PoCs... A Todo List App and a Headless CMS.

The Todo List is simple, but exercises quite a few features without being overwhelming... The Headless CMS is "everything plus kitchen sink".

wtrocki commented 2 years ago

Would that be OpenAPI specifically? Do we look for code generation libraries? Patterns? Sample apps?

InfoSec812 commented 2 years ago

Almost everything I have done to-date is OpenAPI. I am aware that tooling is getting more mature around things like AsyncAPI and the gRPC tooling is pretty decent, I have not yet worked with them as I have not had any demand for them.

mhdawson commented 2 years ago

I think this is covered by https://github.com/nodeshift/nodejs-reference-architecture/blob/main/docs/functional-components/rest-api-development.md, closing. @InfoSec812. @wtrocki let me know if that was not the right thing to do.

InfoSec812 commented 2 years ago

@mhdawson Looks pretty good to me. I would make 2 comments:

  1. Instead of using @stoplightio/prism-http, it is usually easier to use @stoplightio/prism-cli which does not require writing code

  2. I would update references to OpenAPI v3.0 to reference both OpenAPI v3.0 and v3.1 as 3.1 is a technically superior specification.

mhdawson commented 2 years ago

@wtrocki since you put together most of the content on the API section, would like your confirmation on suggestions above

wtrocki commented 2 years ago

+1 for all suggestions