API Spec Version 1.0.0-alpha review

[wusatosi]

Please review Version 1.0.0-alpha and make suggestions.
Post your suggestions and requests under this issue.
v1 Live build at: https://docs.kcibald.com/v1.0.0-alpha

[HeatMint]

The review will be under the following format:
API: API name, issue place(response status code/payload)
type of problem: unclear meaning on API/advice on a redesign of API
specific:
This is why I want to change API, it is because of blalalalala

example:
API: login, 403
type of problem: unclear meaning of API
specific:
What other message can I expect when there's a ban on the user other than "you violated our terms"

[HeatMint]

API: login, 403
type of problem: unclear meaning of API
specific:
What other message can I expect when there's a ban on the user other than "you violated our terms"

[HeatMint]

API: registry
type of problem: advice on a redesign of API
specific:
Not designed at all, double check that again

[HeatMint]

API: fetch feed
type of problem: advice on a redesign of API
specific:
This api is clearly for kcibald raw openpage
As you see, there are two regions for a single feed.
Also, I need last people who replied on the feed as well
This should be discussed more specifically when we find a time

[wusatosi]

API: login, 403
type of problem: unclear meaning of API
specific:
What other message can I expect when there's a ban on the user other than "you violated our terms"

@HeatMint Thanks for the suggestion
The message field for banned_type is not currently considered to be enumerate .
The design decesion of this is to give us flexability and customizable banned message with minimal effort, which means no prediction on what kind of ban there will be in design level, but customize the message when we are issuing a ban.
So my image of how this works is just to show user the message directly, instead of sending different banned type and let the front end devs to convert it to a human readable message.

implemented! see bac7c21

[wusatosi]

API: registry
type of problem: advice on a redesign of API
specific:
Not designed at all, double check that again

Fair, my fault, created issue #32, will implement within 2 days.

Implemented! see bd2ad45

[wusatosi]

API: fetch feed
type of problem: advice on a redesign of API
specific:
This api is clearly for kcibald raw openpage
As you see, there are two regions for a single feed.
Also, I need last people who replied on the feed as well
This should be discussed more specifically when we find a time

Ok, we will discuss the details later.

As you see, there are two regions for a single feed.
I did catch that...

• if you mean there could be multiple events from different regions, it doesn’t matters, cause the feeds field is a list of feed events, which can have different details.
• if you mean there could be two regions within one feed event, what’s it for? I didn’t get it.

Also, I need last people who replied on the feed as well

Didn’t thought about that, thanks! 😃
will open another issue and implement it within 2 days

[wusatosi]

API: fetch feed
type of problem: advice on a redesign of API
specific:
This api is clearly for kcibald raw openpage
As you see, there are two regions for a single feed.
Also, I need last people who replied on the feed as well
This should be discussed more specifically when we find a time

I've checked the spec, it turns out we are not talking about the same event type. the event type in the spec is when a new post appears under a subscribed region.
The event type shown in the open page seem to be a subscription to some person or a single post, who created an reply under a post.
Thus, instead of fixing the existed api, this is a request to create a new event type and subscription endpoint.

let's discuss details here: #33