API version 1.4 is getting closer to release

The_Moose

We have some exciting update news for our API: version 1.4 is not far away from a first release. In addition to major stability and performance improvements, improved status and error responses, there will, as usual, be a few breaking changes. These changes are being made to address some long-term issues related to how regions, images, and plans are viewed.

In version 1.3 and earlier, regions, images, and plans were indexed lists, (unlike everything else). While these indexes made sense in the past, they have started to cause issues and limitations to further improvements on our platform. For instance, a plan index would only hold 1000 different plans, categorized into different layers (e.g., 11xx, 12xx, 13xx, and so on), thereby supporting only 10 different plan types per data center.

The second problem is the lack of consistency, which was mostly noticeable with images. Every time a new image was added or an old one removed, the indexes would change. This would occur when a new version of an OS is released or an older version is removed. For example, you couldn't rely on 1101 always being Debian 9 x64 and 1102 always being Debian 10 x64. Once Debian 9 x64 is removed, Debian 10 x64 becomes 1101 instead.

These issues were addressed many years ago with the introduction of UUID identifiers, which are based on a hash of the name, ensuring permanent consistency. However, the old ID indexes have remained, awaiting removal. Here's how a region looks today. Let's take Stockholm, for instance:

"125": {
            "uuid": "ef76ffb1-adbd-425f-98ee-4f744eb7afe6",
            "city": "Stockholm",
            "state": "Stockholm County",
            "country": "Sweden",
            "continent": "Europe",
            "datacenter_id": 125,
            "features": {
                "virtual_private_cloud": true,
                "ddos_protection": true,
                "block_storage": true,
                "object_storage": false,
                "floating_ip": true,
                "ipv6": true,
                "backups": true,
                "instances": true,
                "custom_iso": true,
                "databases": false,
                "smtp": false
            },
            "ping_ip": "70.34.194.86",
            "latitude": 59.3293235,
            "longitude": 18.0685808,
            "is_public": true,
            "generation": 1,
            "operator_id": "439fc2dc"
        },

In version 1.3 and earlier, this will remain the same until end of life. However, it's important to note that the issue with changing IDs will not only persist but might also worsen over time. Starting from version 1.4 and above, the index will be completely removed. This means that the Stockholm region will look like this instead:

{
            "uuid": "ef76ffb1-adbd-425f-98ee-4f744eb7afe6",
            "city": "Stockholm",
            "state": "Stockholm County",
            "country": "Sweden",
            "continent": "Europe",
            "datacenter_id": 125,
            "features": {
                "virtual_private_cloud": true,
                "ddos_protection": true,
                "block_storage": true,
                "object_storage": false,
                "floating_ip": true,
                "ipv6": true,
                "backups": true,
                "instances": true,
                "custom_iso": true,
                "databases": false,
                "smtp": false
            },
            "ping_ip": "70.34.194.86",
            "latitude": 59.3293235,
            "longitude": 18.0685808,
            "is_public": true
        },

Now, for regions specifically, the index IDs, which have a lot more dependencies and reliance for information, the ID will remain as a new key called datacenter_id, and will remain unchanged for a foreseeable future. However, for images and plans, there will be nothing to replace the integer index ID. Instead, use the uuid.

From version 1.4 onwards, we have ensured that both the id index and uuid are supported in all actual function calls, and incorrect values will be corrected in the back-end. If more breaking changes are introduced in version 1.4, we will, of course, announce them well ahead of time. Version 1.3 and below will remain as they are.

Our own control panel at dash.99stack.com will switch over to version 1.4 within the next few days.

Marco_Weiss

I did notice how the ID's changed and it was really annoying. But after switching to uuid instead my apps works just fine. For anyone else courious in how to stay up to date you can run something like:

$ curl -I https://api.99stack.com/v1.3/region/list

HTTP/2 405 
date: Sat, 27 Apr 2024 15:58:05 GMT
content-type: application/json
access-control-allow-methods: GET, POST, PATCH, PUT, DELETE, OPTIONS
access-control-allow-headers: origin, authorization, content-type
access-control-max-age: 86400
content-security-policy: default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; img-src 'none'
server: cn-man1
x-robots-tag: noindex,noarchive
x-version: 1.3
x-deprecation-notice: This version has reached end of life, please update your application to the latest version of 99Stack Cloud API. Learn more at: https://api.99stack.com/docs/
x-frame-options: SAMEORIGIN
access-control-allow-origin: *

And pay attention to the x-deprecation-notice header as it tells when a function is outdated and will eventually be removed. There's also a Deprecated boolean header on some very old functions if I remember correct. This is how the same curl command looks if we call v1.4 now:

$ curl -I https://api.99stack.com/v1.4/region/list

HTTP/2 405 
date: Sat, 27 Apr 2024 15:58:05 GMT
content-type: application/json
access-control-allow-methods: GET, POST, PATCH, PUT, DELETE, OPTIONS
access-control-allow-headers: origin, authorization, content-type
access-control-max-age: 86400
content-security-policy: default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; img-src 'none'
server: cn-man1
x-robots-tag: noindex,noarchive
x-version: 1.3
x-frame-options: SAMEORIGIN
access-control-allow-origin: *

Also, correct me if I'm wrong but it seems that dash has now fully switched over to v1.4?

The_Moose

Marco_Weiss Deprecation notices via headers was introduced many years ago, good to see that it's of help. And yes, the dashboard now runs entirely on v1.4 with a lot of UI improvements released today.

George_Hegland Within a few days, but until then you can use the v1.3 documentation as it's mostly similar. Except for the following endpoints:

/v1.4/region/list
/v1.4/image/list
/v1.4/plan/list

Were the output differs slightly. If you already use uuid in your apps, this upgrade should not cause any breaking changes at all.

George_Hegland

When will the documentation for v1.4 release?

Orson_Deforest

Looks good, I was always paranoid requesting create, before first checking plans and images.

The_Moose

Starting today, the following functions will be renamed in v1.4 and ahead:

/account/token_list -> /token/list
/account/token_create -> /token/create
/account/token_rename -> /token/rename
/account/token_remove -> /token/remove

Old function references will remain but include a Deprecated: true header. The reason for this is consistency and to avoid functions with a _ in it's name, such as this particular case were /account/token_ simply becomes /token/ as token is now it's own class/object.

More functions with a _ in them will be renamed too, but with backwards compatibility preserved.

Herman

Reminds me that I haven't yet updated my app since 2018. I think the public endpoints have changed since then too. The functions at least but not the output. I really appreciate the backwards compatibility. 👌

Kenneth_Crayton

Herman Probably best to do that soon, the new ones look a lot nicer and utilize methods better.

The_Moose

Another change for v1.4: In /account/register you will no longer specify firstname and lastname. Instead use name which is your full legal name. This can be compared to data from payment processors if there's any suspicion of fraud going on, or a fake account using stolen cards.

This field also provides more flexibility compared to the dual name system were you can enter all names (if you have more than two), or just your first name, or a user name if you prefer. The field should support non latin characters as well.

Boris_Zaitseva

Looks good, these inconsistencies were always hard to remember.