Migrating an SDK from 0.2 to 0.3
SDK 0.3.0 renamed every operation, in every language. If you are on 0.2.x and you upgrade, your code will not compile, or in Python and Ruby will fail at the call.
Why it happened
The OpenAPI specification carried an operationId for 105 of its 185
operations and not for the other 80. The generator falls back to the route
when one is missing, which produced a client where api.listUsers() and
api.v1SendPost() sat in the same file.
All 185 now have one, so the names come from what the operation does rather than from the URL it happens to live at.
The renames you are most likely to hit
| Was | Is |
|---|---|
v1SendPost |
sendEmail |
v1SendBatchPost |
sendEmailBatch |
v1MessagesGet |
listMessages |
v1MessagesIdGet |
getMessage |
Casing follows each language: Python gets send_email, Go gets SendEmail,
C# gets SendEmailAsync.
Models were renamed to match. V1SendPostRequest is SendEmailRequest,
V1SendPost200Response is SendEmail200Response, and
V1SendPostRequestAttachmentsInner is SendEmailRequestAttachmentsInner.
Python module paths changed with them:
lockally.models.v1_send_post_request is now
lockally.models.send_email_request.
Finding out whether you are affected
Search your codebase for v1 followed by a capital letter, or for
v1_send:
grep -rnE 'v1[A-Z][a-z]|v1_[a-z]+_(post|get|patch|delete)' .
Every hit is a call that needs renaming. In a typed language the compiler
finds them for you; in Python and Ruby it will not, and the failure is an
AttributeError or NoMethodError at the moment you send.
Go: never use v0.3.0
lockally-go@v0.3.0 is permanently broken and cannot be fixed, because the Go
module proxy is immutable: a published version can never be replaced, only
superseded. v0.3.1 is the one to move to, and anything resolving to
v0.3.0 should be pinned past it explicitly.
The framework packages
The ten framework wrappers (Django, Laravel, Express, NestJS, Rails, Symfony, Flask, FastAPI, Spring Boot, ASP.NET Core) call the SDK on your behalf, so the rename reached them too.
Use 0.2.0 or later of the wrapper. The 0.1.0 releases were written against the pre-0.3.0 SDK, and where their pin allowed a newer SDK they fail on the first send.
If you are staying on 0.2.x
That is supported and nothing forces the move. Pin exactly:
lockally==0.2.1 # pip
"lockally": "0.2.1" # npm, exact rather than caret
You will not receive new endpoints or fields added since, which is the cost.
The API itself is unchanged by this: /v1 did not move, and a 0.2.x client
still talks to it correctly.