Wrote OpenAPI Spec for Self-Defined #72
Conversation
After looking at some of the issues, and taking a look at the site, I made a bunch of guesses at where you would want to take the app with use and such and put together this API Spec to cover those stated and projected goals from the API perspective.
|
@hibaymj FYI: I’ll have a closer look at this in the coming days. Haven’t forgotten it, just a lot on my plate right now. |
|
@ovlb Do you still have a desire to review this? If not, I can see if someone else can! |
|
@tatianamac As I, finally, have more time at hand, I will catch up with the API discussion and review this PR in the course of the week. |
|
Thanks so much for this. I’m no API expert, so I might miss some things. Here are a bunch of questions that sprung to mind:
Sorry that it took me ages to get back to you. 😊 |
|
This was very much a "foundation" to build on, less a finished API contract.
1. I think you would definitely want to mark some of these operations for
specific authorizations and such. That obviously requires the attention of
someone read into the way that's going to be accomplished, and since I'm
not, I couldn't do that.
2. NewWord has different requirements than word, Id not being present, and
some other lifecycle differences. FullWord I believe was when you wanted to
have all of the word and referred sub elements, which isn't necessarily
what you would want in all cases for different displays. This in general
was just a way to offer some control over the data shape without invoking
some really hefty to include components.
3. Yea, it's been a while since I saw the underlying material, or wrote up
this contract. However, I think the idea was to support the front end or
social ability to link to a word with a shorter URL, for things like
twitter. I believe this was a large purpose of this tool, so I figured why
add a shortlink service step?
…On Sun, May 17, 2020 at 8:58 AM Oscar ***@***.***> wrote:
@hibaymj <https://github.com/hibaymj>
Thanks so much for this. I’m no API expert, so I might miss some things.
Here are a bunch of questions that sprung to mind:
- Can we mark some routes as requiring auth/mark them as part of the
private API in comparison to the public API (mostly all GET requests)?
- You have a schema for Word, for NewWord and FullWord could you
expand on the differences/use cases for each?
- Shortlink is a kind of abbreviated definition we could e.g. use to
render the overview?
Sorry that it took me ages to get back to you. 😊
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#72 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/ADBEZNE46CRTY5O6GKV72YLRR7NN7ANCNFSM4KVBEMCQ>
.
|
| word: | ||
| $ref: '#/components/schemas/Link' | ||
| required: | ||
| - shortLink |
There was a problem hiding this comment.
Should this be shortLinkText to match the property
| - shortLink | |
| - shortLinkText |
| Translations: | ||
| type: object | ||
| properties: | ||
| translations: | ||
| type: array | ||
| minItems: 0 | ||
| items: | ||
| $ref: '#/components/schemas/Link' | ||
| Synonyms: | ||
| type: object | ||
| properties: | ||
| synonyms: | ||
| type: array | ||
| minItems: 0 | ||
| items: | ||
| $ref: '#/components/schemas/Link' | ||
| Alternatives: | ||
| description: A positive alternative choice to communicate without exclusion. | ||
| type: object | ||
| properties: | ||
| alternatives: | ||
| type: array | ||
| minItems: 0 | ||
| items: | ||
| $ref: '#/components/schemas/Link' |
There was a problem hiding this comment.
Should the Translations, Synonyms, and Alternatives be Word types instead of Link types? We can have them in their own containers rather than embedded in the Word object themselves.
| type: array | ||
| minItems: 0 | ||
| items: | ||
| $ref: '#/components/schemas/Link' |
There was a problem hiding this comment.
Should the Translations, Synonyms, and Alternatives be Word types instead of Link types? We can have them in their own containers rather than embedded in the Word object themselves.
| $ref: '#/components/schemas/Link' | |
| $ref: '#/components/schemas/Word' |
| type: array | ||
| minItems: 0 | ||
| items: | ||
| $ref: '#/components/schemas/Link' |
There was a problem hiding this comment.
| $ref: '#/components/schemas/Link' | |
| $ref: '#/components/schemas/Word' |
| type: array | ||
| minItems: 0 | ||
| items: | ||
| $ref: '#/components/schemas/Link' |
There was a problem hiding this comment.
| $ref: '#/components/schemas/Link' | |
| $ref: '#/components/schemas/Word' |
| originLanguage: | ||
| type: string | ||
| description: This should be the ISO internationalization value. | ||
| tag: |
There was a problem hiding this comment.
Tag should be an array because multiple tags might apply. I like the enum but it might be better to allow it to be dynamic and let the API implementation and/or web front end enforce rules around how they're created/added to the word.
|
@hibaymj Do you mind opening a new PR for this? I changed the repo name and migrated it and it auto-closed every PR. 🙃 Thank you! |
After looking at some of the issues, and taking a look at the site, I made a bunch of guesses at where you would want to take the app with use and such and put together this API Spec to cover those stated and projected goals from the API perspective.