fern-api / fern Goto Github PK

The generated SDK should make it very easy to 1/ iterate over all pages, 2/ ask simple questions like .is_next_page_available(). In order to do this the Fern Definition must understand what the pagination scheme is.

@zachkirsch what do you think about having filepath in service as well?

Then add to the Readme example.

DayOfWeekService:
      auth: none
      endpoints:
        getCurrentDayOfWeek:
          method: GET
          path: /day-of-week
          response: DayOfWeek

Our opinion is that many devs will don't actually care about the method or path of the endpoint as long as they can declare inputs and outputs.

Fern should support devs not specifying method or path. It can default method to POST and path to the endpoint id. This provides the flexibility to integrate existing APIs while allowing devs to iterate faster on their APIs by reducing config required.

• Postman has first class support for socket io: https://blog.postman.com/postman-now-supports-socket-io/

Example of API using them

If docker daemon is running we should have a validation error and point users to https://docs.docker.com/get-docker/ (really the specific link based on their OS)

to make it extra clear what that package is

Creating issue where we can jot down all validations we have to add:

e.g. queryParameters vs auth-override

Blocked on prettier/prettier#12763

But first make sure it's actually faster

Support binary as a first class primitive in the spec.

tip?: double instead of tip: optional< double >

Easier readability, follows typescript convention

So we can default to it! instead of making the client enter it manually

created_at_utc: "1981-11-30T10:44:38.567Z"

https://birchsolutions.slack.com/archives/C0222UL3XS9/p1651200517793859?thread_ts=1651199301.661399&cid=C0222UL3XS9

joinPaths takes null strings but I don't think we need it

@dannysheridan encountered a case where a set of endpoints take the same 10 query-params. It's annoying to copy paste them everywhere and changing one things requires you to make edits in n different places.

Should we have a concept of grouped query params?

It should be really easy for the FE to subscribe to "topics", and easy for the backend to send those updates to each FE

The IR should generate unique names for HTTP requests & responses (WireMessage should be a TypeDefiniton instead of a Type)

Take a look at the run codegen stage in this CircleCI workflow: https://app.circleci.com/pipelines/github/fern-api/fern/415/workflows/e78eefec-5405-405e-a961-e7b7db9add7d/jobs/873. We need to provide a --event-based output option that only logs changes (cdk does something similar).

Allows an easy way to handle pre-existing JSON

We can often find the sourceFile from declaration.getSourceFile()

In #130, we switched to depending on @zachkirsch/prettier since there's a bug in prettier re dynamic requires with webpack. The fix is in prettier/prettier#12797, once that merges + releases, we should switch back.

Rules for a linter to evaluate given the input of fern.yml

i.e. string matches regex, int is positive, string is an ISO 8601 date

This is platform dependent re the file system, and thus isn't good for URLs. Same with postman plugin!

I think the yaml is cleaner when it reads like

storeTracedWorkspaceV2:
        http: POST /store-workspace-trace-v2/submission/{submissionId}
        path-parameters:
          submissionId: submission.SubmissionId
        query-parameters:
          stuff: Stuff
        body: list<submission.TraceResponseV2>

as opposed to

storeTracedWorkspaceV2:
        http: POST /store-workspace-trace-v2/submission/{submissionId}
        parameters:
          submissionId: submission.SubmissionId
        query-parameters:
          stuff: Stuff
        body: list<submission.TraceResponseV2>

What are the best practices about where to put objects relative to each other?

How ought a dev organize their objects as they relate to their services? I think the first object mentioned in Services should be the first listed in Objects. The second object mentioned in Services should be the second in Objects, and so on.

Could we encode the best practices in a linter or validation?

fern generate --name would run that generator. The problem is that you can have the same generator multiple times so how do you differentiate across those?

Enums should have a name and value field. If the enums are alphanumeric then value defaults to name, but if not then name needs to be specified so that codegen can be done properly.

I want to know:

• Which endpoints are being hit the most?
• Size of request/responses
• Histogrammable & filterable errors

Other:

• Rate limiting
• SLA management

It doesn't make sense to extend union, enum, or an alias because it is unclear what the extended type would look like (i.e. why would I ever extend a union instead of adding it as a field).
We should validate that only objects are allowed to be extended.

It lets you add dependsOn!

https://turborepo.org/docs/core-concepts/pipelines

Rather than just a top-level errors/model/services

It would be cool if fern visualize would fire up a local ui where you can edit and changes are written back to your yaml files.
No code UI at the edge

Add an example spec to the Fern repo. It should include Rest + Websockets.

The rules for the wire format are a little tricky (depending on if the unioned type is an object or not). Better to encode this in the IR than to do it correctly in each plugin.

Once we have strongly-typed plugin config, we can make the type of output a "filepath" so we know to map it on the container

@zachkirsch i think every wire message should have an id that makes it very easy to trace through your api while debugging. The IDs have been invaluable in my experience and fern is in a great position to bake them in.

Can see us building a self-hostable analytics tool on top that can track those IDs and make it very easy for PMs + Devs to understand metrics/filter.

A command-line command of fern validate that takes my YML and checks for mistakes/errors before I run fern generate