HTTP API upgrade

Developers Tools
,
1

Hey everyone, we’re making a significant upgrade to the map format, which means you’ll need to update your http API usage. I’ve set it up so everyone can transition at their own pace when they’re ready.

As soon as convenient, please:

  • Transition any use of the v1 http API (/api/getMap) to the v2 (/api/v2/spaces/:space/maps/:map). This was a shift we made years ago but I’m finally going to delete the old endpoints and there are still a few stragglers.
  • With the v2 API, pass useV2Map=true as a query param and confirm that your stuff still works. The examples in the docs have already been updated.

Here are the changes between this and the previous version:

  • spaces and desks are not allowed, only nooks (previously auto-converted).
  • objects are now an object, with base64-url-safe (a-zA-Z0-9-_) string keys of length <5. Each one is the same as before plus one new required field, zIndex (>=0), which determines what’s on top, instead of the array order in the previous version.
  • The objects in objects are now validated more, including requiring x, y, normal, type, width, and height on all of them.

Once everyone has had a chance to migrate, I will make useV2Map=true the default behavior, remove support for the old format, and you won’t need to pass that param any more.

If you need more than two weeks to update, DM me and I’ll make sure to wait for you.

Feel free to reply in this thread with any questions!

2 Likes
2

Hello! Is there any kind of API description document available, such as an OpenAPI description file or similar?

Thanks!

3

The notion site is about all there is. Here

4

Thanks Bill!

I should have mentioned, I’m aware of the “Gather HTTP API” Notion page and appreciate the documentation there, but was wondering if there is anything like a OpenAPI description file to act as a source of truth and that we could generate a client from.

It sounds like the answer is no so that’s all good.

Is there any official stance on whether we might get such a thing down the line or if it is in fact a non-goal?

Thanks again!

5

Yeah sorry nothing like that exists at the moment, and we don’t have any plans to add it in the near future. Let me know if there’s any way that Notion doc could be clearer though!

1 Like
6

Hi, first of all thank you for updating the api. then, any ideas why this is happening?

`{`
`    "error": "UNKNOWN",`
`    "message": "An unknown error has occurred."`
`}`

the body

image
image695×328 6.77 KB

the headers
image
image718×234 10.4 KB

and the url
image
image777×78 7.48 KB

7

It’s the spaceId – %2F is /, but should be \ (%5C). Sorry about that… We keep tripping over this internally too but space ids are so deeply ingrained it’s really hard to fix

Also sorry this error is so unhelpful – I’ll fix it.