chore: initialize repository #2

magicmatatjahu · 2021-10-18T13:55:29Z

Description

Initialize repository:

create OpenAPI doc for server api in openapi.yaml file
add needed dependencies for development in package.json
add Readme.md
update License

Related issue(s)
See asyncapi/studio#86

magicmatatjahu · 2021-10-18T13:56:17Z

openapi.yaml

+            application/json:
+              schema:
+                $ref: '#/components/schemas/Template'
+        '422':


I'm not sure if this is the right code if someone gives the wrong body shape - e.g. not allowed template field or invalid AsyncAPI. Any thoughts?

422 is used whenever the syntaxis is correct and understandable by your server, meaning the JSON or YAML is valid, but semantically it isn't, like your example of not allowed template field. So in this case, makes sense to me.

However, for the other example invalid AsyncAPI, 400 status code fits better since it will mean the syntaxis is wrong.

So I think we can add both status codes so we can differentiate the source of the errors.

magicmatatjahu · 2021-10-18T13:56:43Z

openapi.yaml

+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+
+servers:
+  - url: http://api.asyncapi.io


We should change it, but for what? (:

tbh, I like it as it is. Just a little but important change:

Suggested change

- url: http://api.asyncapi.io

- url: https://api.asyncapi.io

Hah, thanks! But I had in mind for what domain 😅

Hah, thanks! But I had in mind for what domain 😅

Yeah, and for me api.asyncapi.io looks ok.

Use api.asyncapi.com instead. We should start getting rid of the .io domain. It was used for historical reasons.

magicmatatjahu · 2021-10-18T13:57:14Z

openapi.yaml

+        template:
+          type: string
+          description: Template name to be generated.
+          enum:
+            - 'html'
+            - 'markdown'


In first iteration we will only support these two templates.

smoya

Looks good to me! Just dropped few review comments.

Also please remove.DS_Store file.

README.md

smoya · 2021-10-19T10:33:56Z

openapi.yaml

+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+
+servers:
+  - url: http://api.asyncapi.io


tbh, I like it as it is. Just a little but important change:

Suggested change

- url: http://api.asyncapi.io

- url: https://api.asyncapi.io

smoya · 2021-10-19T10:40:07Z

openapi.yaml

+  - url: http://api.asyncapi.io
+
+paths:
+  /generate:


I have two suggestions regarding this endpoint:

1. API Versioning

I would suggest we start right now doing API versioning through the URI. I would add it so we can always differentiate from v1, v2, etc. Examples:

https://api.asyncapi.io/v1/generate

https://api.asyncapi.io/v2/generate

See https://www.freecodecamp.org/news/how-to-version-a-rest-api/

2. Add more resource semantics to the URI.

I see /generate says not a lot about what the endpoint does. It generates, but I don't know what are we generating if I don't read the documentation.
I would suggest we add the resource we are generating as part of the URI. Depending on how we want to approach the API in terms of design, some options could be:

/generate/template

Would we generate anything else apart from templates? Would it make sense in the future to have also (just an example) /generate/uml ?

/template/generate

Would we do more things with templates? For example /template/convert ?

Hmm. This idea with generate/template is good, then we can extend it by generate/models and other things to split functionality to separate paths.

About versioning, we can go with alpha in first version and then switch to v1, or go with v1 from beginning. To be honest I was writing backend servers just only for fun and don't know what the best practices are.

I think it's better to start with the v1 or 1 since the beginning. No matters as it is in development phase (alpha version here) you will turn it to the final version eventually, creating all breaking changes that are needed during that period.

Ok I changed to the /v1/generate/template - OpenAPI doesn't still support versioning so we need to add version to every path

Not sure if makes sense to use different servers for this? Like one server with the suffix /v1 on the URL, etc.
But anyway, I think it is ok like you did now.

Then just use another model like /generate/:templateName, /convert/220/to/300 or similar. Read a bit about RPC over HTTP. Not everything has to be REST or GraphQL 😉

/generate/:templateName was discussed in this thread and we decide to go with /generator and template will as one of the payload's fields.

For /convert/220/to/300 I think that having from and to versions in request body will be better 😄

Ok, just a thought: if you go for /convert with from and to as payload fields, you should go for /generate and not /generator.

Damn, missed that comment 😅 Yeah, right, but instead of describing resources as a verb we should describe as a noun (we discuss about it in this thread), so it would be /converter rather than /convert. Thanks for the observation!

Yeah, I saw the convo. I just don't think converter and generator are resources. What is POST /generator supposed to do? Create a generator? No, right? I think your design is more RPC than REST, which is fine, just don't stick to REST rules if it's not REST. My two cents.

openapi.yaml

smoya · 2021-10-19T10:57:44Z

openapi.yaml

+            application/json:
+              schema:
+                $ref: '#/components/schemas/Template'
+        '422':


422 is used whenever the syntaxis is correct and understandable by your server, meaning the JSON or YAML is valid, but semantically it isn't, like your example of not allowed template field. So in this case, makes sense to me.

However, for the other example invalid AsyncAPI, 400 status code fits better since it will mean the syntaxis is wrong.

So I think we can add both status codes so we can differentiate the source of the errors.

openapi.yaml

magicmatatjahu · 2021-10-19T11:18:01Z

@BOLT04 Do you wanna look at PR? I know that you participated in the discussion, maybe you would like to give some advice? :)

magicmatatjahu · 2021-10-19T11:35:49Z

@smoya Thanks for review! I added your suggestion and answered for your comments :) Could you look again?

smoya

LGTM! 🚀

BOLT04

Hi @magicmatatjahu 🙂, thank you so much for the ping!!! I wasn't aware this repo was created and that this type of work was in progress.

I left some comments, I'd love to have the community's opinion and discuss some topics of this API design.

Thank you again for the ping 👍

tsconfig.json

openapi.yaml

.github/workflows/welcome-first-time-contrib.yml

BOLT04

Super cool, amazing work @magicmatatjahu 👍 and great discussions everyone 😃

@derberg

Comments made by @derberg and @BOLT04 opened my eyes

magicmatatjahu · 2021-11-09T09:45:30Z

@smoya @BOLT04 @derberg @fmvilas I propagated changes that you suggested. Can we merge that PR and any changes/amendments will be added iteratively? Of course, this will be the first version of the API so nothing prevents us from deciding on a different API design in the coming weeks.

BOLT04

LGTM 👍

jonaslagoni

Just had a few comments, in case they are relevant 😄

.github/workflows/automerge.yml

README.md

openapi.yaml

jonaslagoni

LGTM 👍

magicmatatjahu · 2021-11-29T12:36:27Z

Well, it took a while, but finally I will merge it :) Thank you all for the review. If the specification is not correct, we can always change it.

fmvilas · 2021-11-29T12:44:50Z

Great stuff, Maciej! Looking forward for this API 🙌

magicmatatjahu commented Oct 18, 2021

View reviewed changes

magicmatatjahu requested review from derberg, fmvilas, jonaslagoni and smoya October 18, 2021 13:58

smoya requested changes Oct 19, 2021

View reviewed changes

smoya previously approved these changes Oct 19, 2021

View reviewed changes

derberg mentioned this pull request Oct 20, 2021

docs website for the api of the parser asyncapi/parser-js#387

Closed

BOLT04 reviewed Oct 20, 2021

View reviewed changes

tsconfig.json Show resolved Hide resolved

openapi.yaml Outdated Show resolved Hide resolved

.github/workflows/welcome-first-time-contrib.yml Outdated Show resolved Hide resolved

magicmatatjahu mentioned this pull request Oct 21, 2021

chore: add postman platinum and smartbear silver asyncapi/conference-website#66

Merged

BOLT04 approved these changes Oct 21, 2021

View reviewed changes

magicmatatjahu added 10 commits November 9, 2021 10:33

chore: initialize repository

842427d

chore: add placeholder file

e40fe1f

remove blank lines

3e1e8e0

add AsyncAPIDocument schema

63ea955

after first review

2b56f82

add version in the server

31595e6

update description for parameters field

b4411cb

propagate suggestions

3b3feb2

change template to generator

212ffb3

change .io to .com

a84a0ce

magicmatatjahu force-pushed the init-repo branch from 6cd67ac to a84a0ce Compare November 9, 2021 09:33

BOLT04 approved these changes Nov 9, 2021

View reviewed changes

jonaslagoni reviewed Nov 13, 2021

View reviewed changes

.github/workflows/automerge.yml Outdated Show resolved Hide resolved

README.md Show resolved Hide resolved

openapi.yaml Outdated Show resolved Hide resolved

derberg approved these changes Nov 15, 2021

View reviewed changes

fmvilas approved these changes Nov 22, 2021

View reviewed changes

magicmatatjahu added 2 commits November 29, 2021 13:13

Merge branch 'master' into init-repo

6899385

update shape of AsyncAPIDocument schema

0923b09

jonaslagoni approved these changes Nov 29, 2021

View reviewed changes

magicmatatjahu merged commit 6b8bab5 into asyncapi:master Nov 29, 2021

magicmatatjahu deleted the init-repo branch November 29, 2021 12:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: initialize repository #2

chore: initialize repository #2

magicmatatjahu commented Oct 18, 2021

magicmatatjahu Oct 18, 2021

smoya Oct 19, 2021 •

edited

Loading

magicmatatjahu Oct 18, 2021

smoya Oct 19, 2021

magicmatatjahu Oct 19, 2021

smoya Oct 19, 2021

fmvilas Nov 3, 2021

magicmatatjahu Oct 18, 2021

smoya left a comment

smoya Oct 19, 2021

smoya Oct 19, 2021

magicmatatjahu Oct 19, 2021

smoya Oct 19, 2021

magicmatatjahu Oct 19, 2021

smoya Oct 19, 2021 •

edited

Loading

fmvilas Nov 3, 2021

magicmatatjahu Nov 9, 2021

fmvilas Nov 12, 2021

magicmatatjahu Nov 29, 2021

fmvilas Nov 29, 2021

smoya Oct 19, 2021 •

edited

Loading

magicmatatjahu commented Oct 19, 2021 •

edited

Loading

magicmatatjahu commented Oct 19, 2021

smoya left a comment

BOLT04 left a comment

BOLT04 left a comment

magicmatatjahu commented Nov 9, 2021

BOLT04 left a comment

jonaslagoni left a comment

jonaslagoni left a comment

magicmatatjahu commented Nov 29, 2021

fmvilas commented Nov 29, 2021

chore: initialize repository #2

chore: initialize repository #2

Conversation

magicmatatjahu commented Oct 18, 2021

Choose a reason for hiding this comment

smoya Oct 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smoya left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

1. API Versioning

2. Add more resource semantics to the URI.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smoya Oct 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smoya Oct 19, 2021 • edited Loading

Choose a reason for hiding this comment

magicmatatjahu commented Oct 19, 2021 • edited Loading

magicmatatjahu commented Oct 19, 2021

smoya left a comment

Choose a reason for hiding this comment

BOLT04 left a comment

Choose a reason for hiding this comment

BOLT04 left a comment

Choose a reason for hiding this comment

magicmatatjahu commented Nov 9, 2021

BOLT04 left a comment

Choose a reason for hiding this comment

jonaslagoni left a comment

Choose a reason for hiding this comment

jonaslagoni left a comment

Choose a reason for hiding this comment

magicmatatjahu commented Nov 29, 2021

fmvilas commented Nov 29, 2021

smoya Oct 19, 2021 •

edited

Loading

smoya Oct 19, 2021 •

edited

Loading

smoya Oct 19, 2021 •

edited

Loading

magicmatatjahu commented Oct 19, 2021 •

edited

Loading