Proposals for improving endpoint names

davidyuk commented 4 years ago

Drop `static` from endpoint names

Actually, I just can't understand what it means in this context.

Drop `cache` from endpoint names

As an endpoint consumer, I don't care if it a source of truth or it caches some third-party data source (for example, cache/prices endpoint). Also, it is obvious that we are working with cached data if we are fetching something that is already presented in a smart contract. Maybe we can explain that these endpoints caching in the documentation instead?

Unclear and inconsistent usage of `api`

I assume that all endpoints are kind of api, but currently, it is used in blacklist/api/wallet and comment/api/..., I don't see any collisions or misunderstoodnes if we just remove api from that endpoint names.

Combine `/static/stats` and `/cache/stats` into just `/stats`

In superhero-ui they are queried at the same time. In general, I don't see reasons to split these endpoints.

Rename `claim/submit` to `claim`

Sending a POST request to claim endpoint already means submitting some data.

Rename `profile/image/:address` to `profile/:address/image`

To have it consistent with profile/:address endpoints.

Rename `cache/userStats?address=:address` to `profile/:address/stats`

The same as the above.

kenodressel commented 4 years ago

I agree with the general idea that we need to streamline the API naming and come up with a proper convention but we should check our priority on this as it will require changes in all connected clients as well.

thepiwo commented 4 years ago

As an endpoint consumer, I don't care if it a source of truth or it caches some third-party data source

I think in blockchain you should care, this makes clear its a cached representation of some data, espectially NOT the source of truth

Combine /static/stats and /cache/stats into just /stats

we can do, this did happen initially as for static the source is the db and for cache the source is the contract

Sending a POST request to claim endpoint already means submitting some data.

I'd not change that, as its submitting a claim try, not directly claiming

davidyuk commented 3 years ago

I think in blockchain you should care, this makes clear its a cached representation of some data, espectially NOT the source of truth

I'm still thinking that it can be just documented instead. More arguments around this:

cache in a path can break REST in cases if we have an entity that is cached and the user may ask backend to modify it
- GET /cache/tips
- POST /tips/1/report-post
user may guess that he is working with cached data by the fact that he is fetching it from the backend instead of the node
backend doesn't have sense to have a not cached version of endpoints that makes cache prefix rudimentary

I'd not change that, as its submitting a claim try, not directly claiming

I don't see the difference, claiming can fail isn't it the same as submitting a claim try?

aeternity / tipping-community-backend