Adopting the OpenAPI schema to generate Plaid’s SDKs | Hacker News Reader

Adopting the OpenAPI schema to generate Plaid’s SDKs

plaid.com

35 pointsstanleydrew22 comments

Meh, speaking as a user of their new python sdk, the end result is underwhelming. I don't blame OpenAPI but the Plaid team for not putting in much effort.

For example, they want all arguments to be typed. So instead of using DoSomething("US"), they want DoSomething(SomePlaidCountry("US")). It gets extremely verbose -- for no good reason either as it just moves the runtime check in another method, it doesn't remove it. What's more, it doesn't even actually use python typings. In fact it's super incompatible with them because a bunch of their types are generated at runtime, lazily imported, using magic etc which confuses typing engines.

What would this look like it it were any good? Native python types and native enums. But i doubt anyone on their python team has worked with either, as they just reinvented the wheel.

Example issue: https://github.com/plaid/plaid-python/issues/340

~ I'm the author of the article ~

Hello! I'm assuming you're talking about Python type hints: https://docs.python.org/3/library/typing.html.

I love these :). I remember back in uni I would fill my program with them, but then fail the autograder because they were using an older version of Python 3 (support was only added in 3.5). I also remember back when the system didn't even have support for self-hoisting, so you couldn't make recursive type definitions and would have to do string annotations like `(x: 'LinkedListNode')`. Fun times.

Assuming that strongly typing the library in some way is beneficial (which we believed), let's look into the options we're provided here. Python's current type hint system requires external tools to enforce it and isn't enforced at runtime or "compilation." The system we have in our library creates a ton of objects that end up enforcing runtime constraints on input values. Failing at runtime because of invalid input is good. I've worked on Python stacks that totally do not use type hints (and my Emacs setup probably didn't back then either), and would have been saved tons of time debugging if the library just told me I was doing things wrong. This is at a definite cost of verbosity. There are definitely ways we can cut verbosity in this model (enums was actually a great example). Considering we were working on 5 languages at the same time though, it was difficult to do everything we wanted before shipping.

There's also the final reality that the generator we chose to use defaults to this behavior. We didn't find a better OpenAPI generator out there, and we weren't opposed to this generated output. There wasn't much wheel invention here, but we did attempt to make it spin smoother at times :D.

Can anyone point to an example of an OpenAPI generated SDK which they like?

There are strong advantages for maintainers to generate from an OpenAPI spec, but I get the feeling consumers (devs, implementers) don’t like them as much. But that may be dependent on the language, or entirely false. Mostly based on anecdotal feedback, and primarily from those who were happy with an existing SDK and, understandably, didn’t want to change.

I’d be keen to hear what HN users think.

Yeah takes a lot to make a generated sdk good, lots of bad examples, few good ones.

AWS SDKs must be generated and they are mostly good but some of them like S3 are so heavily used they could have teams writing them no probs. GCPs are (or were?) super verbose which is a GRPC generation artifact, same as openapi.

As part of a big project I've worked on, we created a tool to generate Typescript types + runtime validation + SDK (client) from an openapi definition. The tool as been used quite extensively to help in the integration of many services and APIs. https://github.com/pagopa/openapi-codegen-ts

I'm not sure if it's OpenAPI generated but the AWS python sdk (boto3 bindings) is clearly generated in some way. I quite like it, because it's highly consistent so i always know what to expect. Unfortunately it's not typed either.

You can get third party library stubs which will add typing. If you use boto alot I highly recommend it.

Shameless plug: https://pyotr.readthedocs.io/

Stripe uses OpenAPI for some of its SDK generation.

I see Stripe and Plaid SDKs being discussed. Has anyone tried out Square's SDKs: https://developer.squareup.com/docs/sdks#square-api-sdks?

Keen to know some thoughts on the code quality.

I’d like to see a comparison between for example Stripe and Plaid. I see some use case examples on the Plaid website, but it is still all pretty vague to me. Can plaid be used like a regular PSP? How does it compare to Stripe transactions? And Stripe Connect?

They provide mostly non-overlapping features. Stripe = get paid. Plaid = connector into banking data (transaction history on a checking account, or the account # itself, for example). So, if you need to accept payments, or send money, you'd lean towards Stripe. If you instead wanted to get access to a user's financial data, such as if you are writing a budgeting app or personal financial management application, you'd lean towards Plaid.

Interesting, I might have thought there would be some overlap because Plaid allows to initiate payments. Why wouldn’t it be possible to initiate a payment from a users personal account to my business account?

https://plaid.com/use-cases/consumer-payments/ https://plaid.com/docs/quickstart/#setting-up-for-payment-in...

It's possible, but nobody does this because the friction to link an account with plaid is very high. You need to pick your bank then give your username and password to your bank (and potentially a 2fa code etc). All this just to get an ACH and routing number.

Plaid's true value add is normalized access to transactions and other banking metadata. Using it only for payments is not a good UX.

I work at Plaid and I agree that using Plaid just for getting an ACH and routing number leaves a lot of value on the table. You're getting more than an ACH number and and routing number though -- you're also getting proof that the person can log in to the bank account associated with that account/routing number combo, which is really helpful for fraud reduction -- fraud in online payments is a huge problem and part of the reason many of our customers use us. (You also get, if you want it, a token that you can use directly with Stripe, Dwolla, etc. to do the funds transfer.) Another popular use case is to use the Plaid Auth API for ACH and routing number, but then also use the Plaid Identity API (again, for fraud reduction) and/or the Balance API (to help make sure that the payment won't bounce).

That was wat I was worried about as well. Thank you for making it clear to me.

Plaid is not a payment service at all. There's almost no overlap.

Plaid is mostly a screen-scraper of banking data. Users give you their banking credentials and plaid gives you scraped transaction history.

https://plaid.com/use-cases/consumer-payments/ https://plaid.com/docs/quickstart/#setting-up-for-payment-in...

Good work, SDKs are necessary for anyone selling an API and OpenAPI is currently the best way to generate them.

Actually creating a startup around this: https://sdkeasy.com

I recently wrote a blog to help teams decide between writing the SDKs for their APIs by hand or generating them using a code generator: https://www.apimatic.io/blog/2021/09/the-great-sdk-battle-bu...

TLDR: There are a good many technical challenges to creating high-quality SDKs in multiple languages for a medium to large-sized REST API and most teams seem to underestimate the amount of effort required to build and maintain SDKs. The speed and savings from code generation is quite compelling and a modern commercial code generator like APIMatic has a wide-enough feature-set that most REST APIs don't require writing SDKs by hand anymore.

Disclaimer: I am a contributor to APIMatic Code Generator.

Does apimatic use the following open-source code generators or it builds a proprietary code generator from scratch?

Swagger Codegen: https://github.com/swagger-api/swagger-codegen

OpenAPI Generator: https://github.com/OpenAPITools/openapi-generator

AutoRest: https://github.com/Azure/AutoRest

NSwag: https://github.com/RicoSuter/NSwag

oapi-codegen: https://github.com/deepmap/oapi-codegen

go-swagger: https://github.com/go-swagger/go-swagger

No, we built our first code generator from scratch in 2014 [1]. I don't think most of these projects existed at the time. Our current CodeGen has always been written-from-scratch, propriety code. Our focus is also a bit different from these projects: we aim to cover as much of the OpenAPI format feature-set while generating consistent, high-quality, well-designed SDKs (should be as good as a good engineer can produce). To complete the Developer Experience of the API, we also generate complete API documentation site as well [4].

Back in 2014, OpenAPI didn't even exist. The latest API specification format was Swagger 1.2 and it was not very mature at that point. We had to build a lot of vendor extensions to cover the various REST API use-cases that API folks take for granted today.

Today, we also run the most-used API Spec format convertor tool in the world by the name of API Transformer [2]; this tool has helped a lot of companies migrate from an older spec formats like OpenAPI 2 and RAML to OpenAPI 3. We support nearly all API specification formats including RAML, OpenAPI (2., 3.), Blueprint, Postman, WADL and more.[3]

[1] https://www.apimatic.io/about/ [2] https://www.apimatic.io/transformer/ [3] https://docs.apimatic.io/api-transformer/overview-transforme... [4] https://www.apimatic.io/developer-experience-portal

Reply on news.ycombinator.com