fern-api / fern Goto Github PK

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

e.g. queryParameters vs auth-override

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

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

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>

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

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

to make it extra clear what that package is

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.

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).

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?

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.

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.

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.

Support binary as a first class primitive in the spec.

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.

Allows an easy way to handle pre-existing JSON

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

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

Easier readability, follows typescript convention

I want to know:

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

Other:

• Rate limiting
• SLA management

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.

Example of API using them

@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.

@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?

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

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)

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

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

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

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

Then add to the Readme example.

It lets you add dependsOn!

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

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

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

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

Blocked on prettier/prettier#12763

But first make sure it's actually faster

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

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

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

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?

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