Proposal API contract #7962
Proposal API contract #7962
Conversation
docs/APIContract.md
Outdated
|
|
||
| ##### League | ||
|
|
||
| The values should be matching what Grinding Gear Games will be using for the teaser part of the website, such as: _https://www.pathofexile.com/settlers_ or _https://www.pathofexile.com/affliction_. This allows for easier mapping of the data as neither PoB nor the API will be required to wait for either party. |
There was a problem hiding this comment.
I'd prefer using the numeric identifier, it's also already used within the build xml from PoB. In pobbin I wouldn't have such a mapping and I'd prefer not to maintain it.
There was a problem hiding this comment.
I assume you mean the patch version as in 3.25 being settlers, 3.24 being necropolis and so on instead of the short-hand string?
|
|
||
| | Field | Type | Description | | ||
| | ------------ | ------- | ----------------------------------- | | ||
| | pobdata | string | The Path of Building data | |
There was a problem hiding this comment.
What does this contain, the build code?
There was a problem hiding this comment.
Yes or rather the standard pob code used for sharing builds, so I assume the description should make this more clear?
| | pobdata | string | The Path of Building data | | ||
| | name | string | The name of the build | | ||
| | lastModified | integer | The last modification timestamp | | ||
| | buildId | string | The unique identifier for the build | |
There was a problem hiding this comment.
Unique identifier on the website? Is that a link or just an internal id?
There was a problem hiding this comment.
This should be an unique identifier as it could be used for updating a local cache for said build, it doesn't have to be an internal id to either pob nor the api but it needs to map to exactly one build.
As going further there may be an option long-term to sync builds from sources to PoB and updating with the click of a button instead of manually reimporting.
tl;dr: Unique Identifier provided by source to map to one specific build
|
|
||
| | http code | content-type | response | | ||
| | --------- | ------------------ | ------------------ | | ||
| | `200` | `application/json` | `BuildInfo object` | |
There was a problem hiding this comment.
We probably need more metadata, for example a description/name of the list returned (or multiple?). pobarchives may provide a list of recent builds, pobbin would only provide popular.
This need goes away if every 'provider' can only provide a single list, but currently more is possible.
It must also be possible for the page to return if there are more pages available or at least indicate this was the last page.
There was a problem hiding this comment.
So possibly a wrapper object such as:
{
"totalPages": 100,
"buildInfos": [{}],
}something like this could then be used for assumption based "this is the last page".
Alas I'm still thinking about how multiple sources should be displayed together as in if every source has 10 entries and I have 100 sources I would get 1000 builds in technically one PoB page (ignoring that local pagination simulation is possible).
Paliak
added
long term
Fixes #7389 controversial addition by designing a common API to adhere to.
Description of the problem being solved:
This may be used as a base for designing a common PoB API, which build sites such as: maxroll, icy-veins, pobarchives and so on should adhere to if they want to be able to display builds inside of PoB.
Furthermore it may also be possible for content creators to support this feature by providing a subset of the required API.
In this initial draft there would be an aim towards two so called endpoint types: REST and CSV.
The REST version would be for anyone who wants to support more complex features such as filtering and possibly other features.
Whereas the CSV version would be an option for content creators who may not have the time, money or willingness to support a custom REST API for their builds. This would easily usable by them to either have a simple webserver just hosting a csv file or using GitHub in order to host the builds.
For more information and current thoughts about the API Contract the information can be found in APIContract.md
Steps taken to verify a working solution:
Link to a build that showcases this PR:
TBD
Before screenshot:
TBD
After screenshot:
TBD