Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve, organize and consolidate API contract types #22

Closed
acelaya opened this issue Oct 1, 2023 · 1 comment · Fixed by #75
Closed

Improve, organize and consolidate API contract types #22

acelaya opened this issue Oct 1, 2023 · 1 comment · Fixed by #75
Milestone

Comments

@acelaya
Copy link
Member

acelaya commented Oct 1, 2023

The API contract exposed by this library is sometimes a bit inconsistent.

Try to re-organize it, making it clear what are the types for stuff returned by the API client methods, types for their params, and smaller sub-types which are usually part of them.

One option would be that the first two used the Request and Response suffixes, but that would couple them with the underlying HTTP layer, when in some cases they don't match 1:1

@acelaya acelaya added this to the 1.0.0 milestone Oct 1, 2023
@acelaya acelaya changed the title Improve, organize and consolidate API contact types Improve, organize and consolidate API contract types Oct 1, 2023
@acelaya
Copy link
Member Author

acelaya commented Mar 5, 2024

The final decision is to use this wording: ...Params or ...Data for the arguments representing information being passed to the API, ...List for objects representing the result of a method returning a list of entities, ...Result for methods which perform a mutation (delete, update, etc) and return a type which is not an entity, and simply the entity name for methods returning one entity, both when reading and mutating.

Some examples:

  • listShortUrls: The argument being passed is named ShlinkShortUrlsListParams, and it returns ShlinkShortUrlsList.
  • createShortUrl: The argument is called ShlinkCreateShortUrlData and it returns ShlinkShortUrl.
  • updateShortUrl: The argument is called ShlinkEditShortUrlData and it returns ShlinkShortUrl.
  • getTagVisits: The argument is called ShlinkVisitsParams and it returns ShlinkVisitsList.
  • getVisitsOverview: Returns ShlinkVisitsOverview.
  • deleteShortUrlVisits: Returns ShlinkDeleteVisitsResult.

We will also try to avoid HTTP-related terminology, like query, body, request or response.

And finally, we will not expose as API contract types which are only internally used by the ShlinkApiClient implementation as intermediary types.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Archived in project
Development

Successfully merging a pull request may close this issue.

1 participant