HubSpot Ideas

Lars-Erik

Publish OpenAPI specifications for the APIs

Hi,

I'm not the first to suggest this, and I know there are reasons it's not concrete in a roadmap. See:
https://community.hubspot.com/t5/APIs-Integrations/Public-Hubspot-API-specs-schema-Swagger-like/m-p/...
https://community.hubspot.com/t5/APIs-Integrations/Swagger-documentation-wanted/m-p/293967

However, I would really like to log this as an idea for voting and visibility.

I would really like to be able to point to both OpenAPI 2 (swagger) and OpenAPI 3 versions of the specification.

Regarding the one endpoint that takes an input stream and makes it "impossible" today - just leave it out of the specs for now. Publish all compliant endpoints.

Even publish it without the one inputstream parameter.

 

Having OpenAPI specs will make it a breeze to integrate with for instance Azure Logic Apps, or use tools to autogenerate clients. (Like the "good old days" of WSDL)

HubSpot Updates
March 05, 2021 01:51 PM

Hi folks, 

 

You can now use the following endpoint to access the HubSpot APIs Open API Specifications:

GET

https://developers.hubspot.com/changelog/get-all-publicly-available-open-api-specifications

Check out the changelog announcement here. 

 

27 Replies
amatomike
Member

If it is Open API (pka swagger) spec where can I find the definition(s) for the services. Sorry if this is a dumb question but I can’t seem to find any schema and the term Open Api is used throughout Hubspots own description and documentation.

Cheers

3PETE
HubSpot Employee

@amatomike We use the term Open API in the sense of a programmable interface that is open for developers of HubSpot customers to push and pull information from our platform. At the moment I do not believe we are part of the “Open API Initiative” and have not based our specs on the swagger specification standard.

Not applicable

Hello,
any news on this ? I m searching some yaml swagger open api def for Hubspot API !
br
Xavier

Derek_Gervais
HubSpot Alumni

Hi @xavier.rouhaud,

This is something the team is very interested in; check out the current in-preview version of the Ecommerce Bridge API docs:

http://petstore.swagger.io/?url=https://api.hubapi.com/api-catalog/v0/apis/extensions/v1/ecomm/#/

IsaacTakushi
HubSpot Employee

Hi, @wiebren.

 

Unfortunately, we aren't able to generate a detailed Swagger spec for that endpoint at this time. One day, we hope for all of our docs to be OpenAPI Specification (OAS) compliant, however I can't offer a concrete timeline right now.


In light of this, can I personally help clarify anything about that endpoint?

wiebren
Member

Hi Isaac,

 

Thanks for replying. Judging from your answer, if I would need the Swagger spec for this specific endpoint, I would need it to construct it myself? If that is at all possible, of course. 

 

I did find this link, however: 

https://cloud-elements.github.io/docs/elements/hubspot-crm/ko/api-documentation.html?elementId=168#!.... It does look like the kind of  content that can be generated based on Swagger. I was wondering who is responsible for the content placed on Github?

 

Thanks, Wiebren 

 

IsaacTakushi
HubSpot Employee

Hi, @wiebren.

 

My understanding is that we can programmatically generate Swagger specifications for many of our endpoints but not the contact createOrUpdate endpoint at this time because it takes a raw InputStream. Because this is just a generic stream of input bytes, our tooling doesn't define it in Swagger and the specification is incomplete. It is possible to create a Swagger spec for this endpoint manually.

 

Cloud Elements created and manages those specs. As a company which normalizes APIs into standard formats, they built their own API on top of HubSpot and produced Swagger specs for it.

maelle
Participant

Hello here! I'm working on an R client for the Hubspot API. I'm wondering whether there's any public machine-readable schema available for the API?

 

For all methods it'd contain what's in the docs HTTP method, format, authentication, rate limiting info, headers, product, required scope, optional and necessary parameters, output structure, e.g. in a big JSON.

 

The reason I'm asking is that I'd like to use such a machine readable schema to scaffold the functions in the R client (we want to add wrappers for each GET method at the moment).

 

Thank you!

 

Related posts I found

 

https://community.hubspot.com/t5/APIs-Integrations/Swagger-documentation-wanted/m-p/294289/highlight... "One day, we hope for all of our docs to be OpenAPI Specification (OAS) compliant, however I can't offer a concrete timeline right now." Interesting, but I guess there's already some sort of machine readable version of the API schema used to e.g. generate the docs, but maybe not public then?

https://community.hubspot.com/t5/APIs-Integrations/Are-hubspots-API-s-open-api-spec-or-actually-just... Not sure whether I could get the JSON for all methods, and if so how.

 

WendyGoh
HubSpot Employee

Hi @maelle,

 

Currently, our API public documentation isn't any type of Swagger/OpenAPI Specification (OAS), it's HubSpot form of documentation. Moving forward, the team is definitely looking to be OAS compliant however I can't provide a specific date. 

 

That said, do let me know if there's any endpoint that I can help to clarify on. 

maelle
Participant

Thank you @WendyGohWoman Happy I'm looking forward to using the machine readable schema when it exists, too bad there's none at the moment! Smiley Happy

Lars-Erik
Contributor | Elite Partner
Lars-Erik
Contributor | Elite Partner
IsaacTakushi
HubSpot Employee

Thanks for sharing, @Lars-Erik. I've upvoted the idea!

hashtagdotnet
Member

I too would like to see OpenAPI documentation.  The API docs are great, but having OpenAPI would significantly help in our integrations.

thomashaines
Member

Hi Wendy

 

I do not believe this advice can be correct as of Jan 3 onwards.

 

The entire hubspot-api-php client is being generated from an OpenAPI definitions file.  This is publicly evident / even in the commit at hotspot's github account:

https://github.com/HubSpot/hubspot-api-php/commit/cadc319407fce0ef52a9501fcdefc218fe474d2d

 

You can see PHP client in every file says * Generated by: https://openapi-generator.tech / version: 3.3.4.

 

Given the choice of pre-built api clients is very limited, if you could make available the file used to call the OpenAPI Generator, it would allow developers to call from strongly typed languages such as Rust or Java.  Any reason not to make file available?  The (currently) unavailable file is being relied on for the official client, so any reason not to make it available?

 

thomashaines
Member

The official clients are generated from an OpenAPI file.

Just see github PHP client or node, e.g.

https://github.com/HubSpot/hubspot-api-nodejs/commit/b47a37492e14d31d62c16f7c35bfa6c0460564b7

 

Not sure why the api model spec file being used in both projects is not made available?  It would make developer experience much better, even if you just provided on a "use at own risk" type basis.

 

jgauffin
Member

Since the PHP client seems to be generated, why not just expose it? You can mark it as beta or whatever.

JoeMayall
HubSpot Alumni

Hi folks!

I'm happy to say that our Product team is exploring this idea. Stay tuned to this thread for more info!

 

Best,

Joe

Ideas Forum Manager

SakshiChauhan
Participant

I just wanted to use all the API objects like marketing, events, Owners, Pipelines So I need the dynamic schema. So is there any way to get the metadata for all the Hubspot API Objects?

WendyGoh
HubSpot Employee

Hey @SakshiChauhan,

 

You should be able to find the API schema on our new API docs i.e. CRM API | Owners > At the right side of the endpoint > Under 'Response' > Select 'Schema'.

 

Hope this helps!!