Sunset: Replacing api-catalog-public/v1/apis Endpoint

[hseligson]

Starting November 11th, 2024, we are deprecating the api-catalog-public/v1/apis endpoint, which will be replaced by the new public/api/spec/v1/specs endpoint. The new endpoint provides a different response format to support HubSpot API versioning and will continue to link to the same HubSpot public OpenAPI specs. If you're currently referencing our OpenAPI specs, we encourage you to migrate to the new endpoint as we plan to retire the old service.

What's changing?

We are deprecating the existing api-catalog-public/v1/apis endpoint and replacing it with a new one.

• Affected Endpoint: api-catalog-public/v1/apis
• Replacement Endpoint: public/api/spec/v1/specs

The replacement endpoint will include a new response format. Here is a truncated version of the response:

// Example of public/api/spec/v1/specs response
{
  "results": [
    {
      "name": "Account Info",
      "group": "Account",
      "versions": [
        {
          "version": 3,
          "stage": "LATEST",
          "requirements": {
            "marketing": "FREE",
            "sales": "FREE",
            "service": "FREE",
            "cms": "FREE"
          },
          "introduction": "Use the account information API to retrieve login and security history for your account, as well as usage data for a public app.",
          "useCase": "Your security team wants deeper insight into which internal users are accessing your HubSpot account data and you need to provide the associated activity data.",
          "openApi": "https://private.hubapi.com/public/api/spec/v1/specs/Account/Account Info/versions/144923"
        }
      ]
    },
    {
      "name": "Audit Logs",
      "group": "Account",
      "versions": [
        {
          "version": 3,
          "stage": "LATEST",
          "requirements": {
            "marketing": "FREE",
            "sales": "FREE",
            "service": "FREE",
            "cms": "FREE"
          },
          "introduction": "The account activity API allows you to retrieve login history and security activity for your HubSpot account.",
          "useCase": "You want to build an internal tool for your compliance team to regularly monitor the activity of employees in your company accessing data in your HubSpot account.",
          "openApi": "https://private.hubapi.com/public/api/spec/v1/specs/Account/Audit Logs/versions/144923"
        }
      ]
    },
    {
      "name": "Oauth",
      "group": "Auth",
      "versions": [
        {
          "version": 1,
          "stage": "LATEST",
          "requirements": {
            "marketing": "FREE",
            "sales": "FREE",
            "service": "FREE",
            "cms": "FREE"
          },
          "introduction": "",
          "useCase": "",
          "openApi": "https://private.hubapi.com/public/api/spec/v1/specs/Auth/Oauth/versions/155908"
        }
      ]
    }
  ]
}

For users currently leveraging the api-catalog-public/v1/apis endpoint, we strongly urge you to migrate to the replacement endpoint before the sunset date. 

Reason for Change

This update is being implemented to support multiple versions of HubSpot APIs.

When is it happening?

This change goes into effect on November 11th, 2024.

Questions or comments? Join us below in our peer to peer developer community forum.

[BMUribe]

First of all awesome addition, this new endpoint contains a lot of the specs that were not present on the old catalog. A few bugs, and inconsistencies I've noticed when migrating my generated clients.

Some of the links are not valid because they contain whitespaces or invalid url characters. For instance, the conversations endpoint points to "https://api.hubspot.com/public/api/spec/v1/specs/Conversations/Conversations Inbox & Messages/versions/54902"

instead of  https://api.hubspot.com/public/api/spec/v1/specs/Conversations/Conversations%2520Inbox%2520&%2520Mes...

The same happens with other endpoints such as Subscriptions, Visitor Identification, Manage Event definitions, and many others.  I had to make sure to uri encode every url...

(Nit) inconsistent naming: Actions V4 and  Automation V4. The API version should not be on the name since there's already a version property to capture that information.

[hseligson]

Hey @BMUribe 👋 Thanks for your feedback! I've forwarded it to the lead engineer and confirmed they will address it. Apologies for any inconvenience and we value your input!

[BMUribe]

Hello, I'm following on this I noticed the endpoints were updated. However, the links were not fixed correctly. it seems like the developers chosed to replace spaces with "+",  that doesn'quite do the trick. Most of the endpoints are now broken as a result. 

On my original comment, I suggested to  use a standard uri-encode for the Urls this will make sure the endpoints are accesible. encodeURI() - JavaScript | MDN (mozilla.org)

Example fix in Javascript:

let oldBrokenLink = "https://api.hubspot.com/public/api/spec/v1/specs/Conversations/Conversations Inbox & Messages/versions/54902";

let fixedLink = encodeURI(oldBrokenLink);

console.log(fixedLink);
// https://api.hubspot.com/public/api/spec/v1/specs/Conversations/Conversations%20Inbox%20&%20Messages/versions/54902

This doesn't affect me since I patched it on my end, but others will definitely assume that the links are  not working. 

Thank you 

[hseligson]

Hi @BMUribe - Thank you! We blame the Java library we were leveraging (grr). But this has been fixed! Thank you again for your help with this issue!

[BMUribe]

Thanks for the quick follow up. I'm Looking forward for the updated endpoints 🙂