/meta endpoints would give the user a way to programmatically monitor changes in the API's metadata for various purposes, such as checking the version, seeing what endpoints have been added/removed, if data structures have changed in endpoints, if previously missing/invalid data has been added/corrected. etc.
A happy side effect of this would be that the maintainers of this project would have an excuse to keep a digit changelog for the data, however vague it may be (eg, instead of "corrected clothing styles for [villager] - changed [erroneous] to [correct]" all you'd need is "corrected erroneous data").
Potential Structure
I propose that a URL param be sent on any GET request to /meta or /meta/*; date.
It would take the same form as the date field in /nh/events, so the validation code already exists. The reason I specify date is because the other three fields don't really apply here (hopefully explained below).
This parameter would determine the oldest date for updates to be fetched from, and the would be fetched from all days after that date, up to and including today (if any exist). You can of course also pass today to receive only today's updates.
The returned data from /meta would have the following structure or similar, and each of the top-level JSON keys would be the * in a potential /meta/* endpoint.
{
"version": "<version string here>",
"versions": [
{
"version": "<version string here>",
"date": "<date here>"
}
],
"new": [
{
"name": "<name of the new endpoint here>",
"date": "<date here>",
"url": "<docs url here>",
"description": "<maintainer's description here>"
}
],
"deprecated": [
{
"name": "<name of the removed/deprecated endpoint here>",
"date": "<date here>",
"description": "<maintainer's description here>"
}
],
"fixes": [
{
"name": "<name of the endpoint with fixed/updated data here>",
"date": "<date here>",
"url": "<docs url here>",
"description": "<maintainer's description here>"
}
],
"structure": [
{
"name": "<name of the endpoint with data structure changes here>",
"date": "<date here>",
"url": "<docs url here>",
"description": "<maintainer's description here>"
}
]
}
If some of these things happen very infrequently, and it makes more sense to group them under a generic "updates" or "changelog" field, then that's absolutely a more sensible option.
Cool, but why?
Developers using this API for applications or services need to know when things change so they can change their application accordingly. Having a daily, weekly, or monthly poll for changes that are sent to their email can speed things up much more than reading a backlog or change logs or scanning the wiki-api-feed discord channel for updates amidst a stream of issues (like this one), comments, PRs, and whatever else may be enabled on the webhook.
For me, in the JS API Driver (which I've finally found enough time to work on!) I'm building for this API I would like to include a simple console.warn if they consumer is using something which may have changes they're unaware of. Also during development I want my console to yell at me about any changes so I can ensure my tests, types, and classes are still compatible.
/meta
endpoints would give the user a way to programmatically monitor changes in the API's metadata for various purposes, such as checking the version, seeing what endpoints have been added/removed, if data structures have changed in endpoints, if previously missing/invalid data has been added/corrected. etc.A happy side effect of this would be that the maintainers of this project would have an excuse to keep a digit changelog for the data, however vague it may be (eg, instead of "corrected clothing styles for [villager] - changed [erroneous] to [correct]" all you'd need is "corrected erroneous data").
Potential Structure
I propose that a URL param be sent on any GET request to
/meta
or/meta/*
; date. It would take the same form as the date field in/nh/events
, so the validation code already exists. The reason I specify date is because the other three fields don't really apply here (hopefully explained below).This parameter would determine the oldest date for updates to be fetched from, and the would be fetched from all days after that date, up to and including today (if any exist). You can of course also pass
today
to receive only today's updates.The returned data from
/meta
would have the following structure or similar, and each of the top-level JSON keys would be the*
in a potential/meta/*
endpoint.If some of these things happen very infrequently, and it makes more sense to group them under a generic "updates" or "changelog" field, then that's absolutely a more sensible option.
Cool, but why?
Developers using this API for applications or services need to know when things change so they can change their application accordingly. Having a daily, weekly, or monthly poll for changes that are sent to their email can speed things up much more than reading a backlog or change logs or scanning the wiki-api-feed discord channel for updates amidst a stream of issues (like this one), comments, PRs, and whatever else may be enabled on the webhook.
For me, in the JS API Driver (which I've finally found enough time to work on!) I'm building for this API I would like to include a simple
console.warn
if they consumer is using something which may have changes they're unaware of. Also during development I want my console to yell at me about any changes so I can ensure my tests, types, and classes are still compatible.Urgency
Nice to have