"List blog posts" endpoint returns multiple tag fields. Preference? Tag Names?

Résolue
Highlighted
Contributeur occasionnel

When I make the following request to the "List blog posts" endpoint

GET /content/api/v2/blog-posts?hapikey=demo&limit=1 HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: api.hubapi.com
User-Agent: HTTPie/1.0.3

I get the following response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Date: Thu, 14 Nov 2019 17:21:58 GMT

{
  "limit": 1,
  "objects": [
  {
[...]
"id": 12026507320,
[...] "tag_ids": [], "tag_list": [], "tag_names": [],
[...] "topic_ids": [], "topic_list": [], "topic_names": [], "topics": [],
[...] "url": "http://demo-hubapi.hs-sites.com/example-blog/example-2-blog", } ], "offset": 0, "total": 465 }

 Which includes 7 different fields relating to topics/tags (Which appear to be the same thing?) ["tag_ids", "tag_list", "tag_names", "topic_ids", "topic_list", "topic_names", "topics"].

When pulling a blog with tags (using my client's credentials) these fields look like this:

{
"id": 20126396728
"tag_ids": [5955714144, 5956086381, 5956086805, 5956088273],
"tag_list": [],
"tag_names": [],
"topic_ids": [5955714144, 5956086381, 5956086805, 5956088273],
"topic_list": [],
"topic_names": [],
"topics": [5955714144, 5956086381, 5956086805, 5956088273],
}

(the fact that "tag_ids", "topic_ids", and "topics" are all the same would seem to confirm that "Tags" and "Topics" are the same)

 

The documentation however only mentions "topic_ids":

    "topic_ids list A json list of topic ids from the topics API ( /content/api/v2/topics )"

 

My questions then, are:

  1. "Topics" and "Tags" are the same, correct?
  2. Are all of these fields other than "topic_ids" deprecated?
  3. Specifically, is the "tag_names"/"topic_names" field intentionally removed, and another request to /blogs/v3/topics/:topic-id is required?

Also, miscellaneously, there are a huge number of undocumented fields in the response from the "List blog posts" endpoint. Given that they are also undocumented, are they deprecated and subject to (undocumented) removal?

Répondre
0 Vote / Votes
1 Solution acceptée

Solutions approuvées
Modérateur

Hi @cfluharty,

 

Thanks for digging into this. I've got some responses for you below:

 

1) "topics" and "tags" are the same thing, yes. In-app these used to be "topics". And then at some point in time we made the change to start calling them "tags". I assume we kept anything "topic"-related in the APIs to prevent any kind of breaking change for developers/integrators.

 

2) I think the above answers this one, but I would say the opposite actually. "tags" are the more recent and current terminology. But so far as I know we have no plans to remove "topics" from the endpoints, and this would be detailed in the Changelog here: https://developers.hubspot.com/changelog if that were to happen.

 

3) To be honest I don't really know why tag_list, tag_names, topic_list, and topic_names are returned in the response here if they're just going to be empty, although there may be a good reason for it. But I think the expectation is that yes, you need to make a request to /blogs/v3/topics (https://developers.hubspot.com/docs/methods/blog/v3/list-blog-topics) in order to get the names associated with those IDs. You could store those IDs and compare the "tag_ids" to what you have stored from this endpoint. You'd only need to make another request when you don't have a tag name stored for an associated ID.

 

For what it's worth I agree that the naming ambiguity is a bit confusing here. We are in the process of auditing and updating some of these docs, so I'll put this one one th team's radar. At the very least I think we can add some clarity around the tag/topic issue, and we can certainly update the example response from the "List blog posts" endpoint. It's not that anything has been deprecated and will be removed. It's likely just that fields have been added to this endpoint, and we haven't updated the doc recently.

 

Let me know if you have any other questions here.

 

Leland Scanlan

HubSpot Developer Support
1 Réponse
Modérateur

Hi @cfluharty,

 

Thanks for digging into this. I've got some responses for you below:

 

1) "topics" and "tags" are the same thing, yes. In-app these used to be "topics". And then at some point in time we made the change to start calling them "tags". I assume we kept anything "topic"-related in the APIs to prevent any kind of breaking change for developers/integrators.

 

2) I think the above answers this one, but I would say the opposite actually. "tags" are the more recent and current terminology. But so far as I know we have no plans to remove "topics" from the endpoints, and this would be detailed in the Changelog here: https://developers.hubspot.com/changelog if that were to happen.

 

3) To be honest I don't really know why tag_list, tag_names, topic_list, and topic_names are returned in the response here if they're just going to be empty, although there may be a good reason for it. But I think the expectation is that yes, you need to make a request to /blogs/v3/topics (https://developers.hubspot.com/docs/methods/blog/v3/list-blog-topics) in order to get the names associated with those IDs. You could store those IDs and compare the "tag_ids" to what you have stored from this endpoint. You'd only need to make another request when you don't have a tag name stored for an associated ID.

 

For what it's worth I agree that the naming ambiguity is a bit confusing here. We are in the process of auditing and updating some of these docs, so I'll put this one one th team's radar. At the very least I think we can add some clarity around the tag/topic issue, and we can certainly update the example response from the "List blog posts" endpoint. It's not that anything has been deprecated and will be removed. It's likely just that fields have been added to this endpoint, and we haven't updated the doc recently.

 

Let me know if you have any other questions here.

 

Leland Scanlan

HubSpot Developer Support