Open Api spec

[RBornost]

I see you moved the open api spec to "private" repo, any plans to make this available again in the near future.

While the javascript sdk "works" I find it's error handling and responses severely lacking. Also the "model" support in the sdk is also not the greatest.

I would really prefer to just generate a axios or fetch client from the json api directly.

[unamashana]

Sorry about that - we need to mirror it from our private repo. The Postman collection is kept updated though - https://www.postman.com/magicbell-api/workspace/magicbell/collection/2269098-9f990075-94a8-4ded-b252-a5289b6e3a2f

You should be able to export from there, or use directly in Postman. Do you have a script or a gist of how you are generating the clients? The reason we made the OpenAPI private is to generate it programmatically and then publish it along with types generated from something like Quicktype so it'd help to know how you are generating the client.

Also, thanks a lot for the feedback on the JS client.

[smeijer]

We've uploaded our OpenAPI spec, and implemented a workflow to keep it up to date automatically. Please find the latest version here: https://public.magicbell.com/specs/openapi.json

I am curious about what features you miss in terms of response and error handling. Any info that you're able to share would help improve our SDKs.

If by model support you mean that the methods should return instantiated class objects, like a "new User()" or "new Broadcast()" so you can check types using instanceof, that's indeed not how we've designed the magicbell sdk. We're working with plain objects, which are less heavy.

I am curious about the use cases that we're missing because of this. If you have any examples to share, that'd be most welcome.

[RBornost]

Thank you for exporting it!

[RBornost]

The tools I use is https://github.com/openapitools/openapi-generator and either ttypescript-axios or typescript-fetch generators.

As for your sdk, I expect to get the status code for all errors from the response object (like the Axios Response). I dislike that you chose to throw an error for everything that is not in the 200 range. In my opinion even a 500 response from the rest api is not exceptional and does not warrant a throw. For example when using axios (less so with fetch) I can control if I want it to throw exceptions for non-200 range status codes. Another problem I have is the error thrown. For example in the sdk you exported the error types which includes a "NotFoundError". However, in usage when user is not found a "MagicBellError" is thrown instead.

Basically, I would prefer the response from the sdk to be more like this:
{ statusCode, statusText, data }

As for the models.. I don't need them to be "class" objects, they just need adhere to an interface or type and not a loose json object and return that. So instead of this: (from hovering over the response variable of the return from updateUserByExternalId in vscode)
const response: { external_id?: string | null | undefined; email?: string | null | undefined; first_name?: string | null | undefined; last_name?: string | null | undefined; custom_attributes?: { [x: string]: unknown; } | undefined; phone_numbers?: string[] | undefined; id?: string | undefined; }

I would prefer it to just be "User".

I will say this, your SDK is much better than the new one from Auth0, Theirs is also generated from a rest api spec but all the object names are like "GetUsers200ResponseOneOfInner" and sometimes the same "object" has different names depending on the endpoint called.

Yours is consistent, even if I don't prefer it the style of it, and I can work with it far easier.

Part of my bias is I was C# dev for 20 years, and now I do mostly typescript/javascript.

[smeijer]

Thanks for the details. That makes sense. I see your point about the readability of the returned type, and agree that reading User vs { external_id?: … } would be better. I have to see what's going on there, it's not always clear to me why/when TypeScript chooses to report a single Type or that expanded form.

Thanks for all the other feedback. I can't "fix" it all for you, as personal preference plays a role in a chunk of it, but I'll keep it in mind while working on future versions. I appreciate the thoughtful response.

For example in the sdk you exported the error types which includes a "NotFoundError". However, in usage when user is not found a "MagicBellError" is thrown instead.

That does in fact sound like a bug. I'll look into. Thanks again!

I also think I agree with the responses ({ statusCode, statusText, data }), but moving to that would be a breaking change. So please understand that's not something we can easily fix/change, even when I do agree with you. For better or worse, the choice back then was made to be consistent with the language (fetch-like).

[RBornost]

Thank you for reviewing and considerations of the above. I do understand the breaking changes and how making that kinds of change may never be possible. Sometimes we have to live with decisions, for better or worse.

Thank you!