Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Promoting HTTP APIs to the default #838

Closed
ryanblock opened this issue May 27, 2020 · 14 comments
Closed

Promoting HTTP APIs to the default #838

ryanblock opened this issue May 27, 2020 · 14 comments
Labels
@deploy @architect/deploy enhancement @package @architect/package
Milestone

Comments

@ryanblock
Copy link
Member

ryanblock commented May 27, 2020

Today, and since the beginnings of Architect in 2016, the default API Gateway type has been REST (aka API Gateway v1); later, we added WebSocket API support (aka API Gateway v2) with the @ws pragma.

Earlier this year, API Gateway went GA with their latest API type: HTTP, which promises faster speeds and significantly more affordable pricing (not that we've found API Gateway REST APIs to be expensive to operate, especially when compared to the costs of running a web server fleet).

To provide Architect users early support for HTTP APIs, we created an officially maintained HTTP API Macro. We've continued to monitor the HTTP API product as it's matured and stabilized over the last couple of months, and I'm (personally) ready to promote it to the default API type.

Some of my current findings about HTTP APIs:

  • They now have the basic feature symmetry with REST APIs that we need to make a transparent upgrade
  • They solve, once and for all, the dreaded API Stage Path Part Problem (aka your-api-id.aws.com/staging + your-api-id.aws.com/production)
  • Anecdotal: they deploy very quickly, especially compared to REST APIs
  • Anecdotal: they generally seem to operate as quickly as their REST API equivalents
  • They have significantly less configuration surface area – in my opinion, that's a huge feature
  • AWS has made it clear to us that they believe HTTP – and not REST – APIs are the future of API Gateway

I strongly believe we should maintain backwards compat for existing REST APIs; here's an idea of how we could allow folks to opt into legacy REST (which still does have a far larger number of features and integrations for folks to take advantage of):

@http
type rest
get /foo

Update, added a second idea:

@aws
apigateway rest

And for existing REST API projects that don't have to worry about their URLs changing, they can manually opt into HTTP APIs in much the same way:

@http
type http
get /foo

Update, added a second idea:

@aws
apigateway http

Related concerns

We are long overdue to reintroduce @domains; I don't want to do that twice (once for REST and again for HTTP), so I'd propose that we move forward with HTTP and scope future @domains work only for HTTP APIs. See: #431

Another concern: HTTP APIs introduce a new Lambda payload shape; it's very close to the existing shape, but has some subtle differences. Architect Functions users are already prepared for this as we've already added early support for HTTP.

Decisions

  • Should HTTP be the default?

    • REST APIs are more full-featured, support more integrations / authorizer types, etc.
    • However, Architect does not natively support most of those features; as it stands today, using most REST API features would require the use of Macros; providing a setting to specify REST would ensure anyone who relies on those features still has access to them
  • Is this a breaking change (ie Architect 7.0.0)?

    • It doesn't have to be, I think. We can run a pre-deploy resource query to see what the current API type is, and infer @aws apigateway rest
    • That said, if we do not do this, everyone's URLs would change, and that would absolutely be a breaking change, so we should not do that

Impacts of this change

Customer impact

Ideally little to none; if we poll existing resources, nothing changes for current projects; everyone gets more (theoretical) API deploy speed and a price reduction.

Code impact

Package

Ideally we do our backwards compat pre-deploy resource queries in package so we don't have to run it a second time. However, I know @brianleroux has been refactoring package to remove any network / disk, so we'll have to figure out the best way to ensure the right API is produced by package for deployment in deploy.

Deploy

Likely only a minor impact; post-deploy URL queries may change.

Functions

HTTP API support has already been added; we likely will need to do some additional testing to calcify req/res payload shapes for HTTP's Lambda v2 payload type, but I don't anticipate anything much there.

Everything else

Likely no (or only minor) impact.

Docs impact

Minor, most things stay the same.

@ryanblock ryanblock added enhancement @deploy @architect/deploy @package @architect/package labels May 27, 2020
@jgallen23
Copy link

jgallen23 commented May 27, 2020

We had to change a fair amount of our code when we went to http apis - mainly around the incoming request payload changes. I would vote this is a breaking change

@ryanblock
Copy link
Member Author

ryanblock commented May 27, 2020

@jgallen23 per the Is this a breaking change (ie Architect 7.0.0)? section, you'd say this should be a breaking change even if, as an existing user with a REST API, nothing changes for you? (As an existing user with a REST API you would have to manually opt into updating to HTTP APIs – your day to day experience with Architect would be unaltered until you opted into HTTP.)

@jgallen23
Copy link

jgallen23 commented May 27, 2020

I guess if you are doing the detection (I missed that part), then maybe it doesn't have to be breaking, but then docs might get a bit confusing if both are the default but it depends if you launched arc previously or not. Seems easier to just say, as of 7.0.0, http api is default and no more production/staging urls and here's the new payload structure.

@ryanblock
Copy link
Member Author

ryanblock commented May 28, 2020

Post 7.0.0 we'd still have to retain docs for REST APIs, especially since we'll continue to officially support both for quite a while (really, presumably as long as AWS does, so assume FOREVER). Any potential docs confusion, while a super valid concern, is also a a separate one from the major bump.

Otherwise, I'd say if this is an additive, forward compatible change, I'm not able to come up with any other reasons to bump major.

@brianleroux
Copy link
Member

brianleroux commented May 28, 2020

Decisions

Should HTTP be the default?

Yes

Is this a breaking change (ie Architect 7.0.0)?

Think we can thread this needle and make this non breaking and additive as Ryan mentions. By making #architect/deploy a bit smarter it can check the type before deploying and branch the generated CloudFormation should RestApi fallback be required. Upgrading can be an additive flag. Would like to keep @http the same and do any of the AWS specific configuration, such as upgrading, to @aws. Ryan suggested something like

@aws 
apigateway rest

Which I like. This means people with the existing 1.0 request/response payloads can opt into HttpApi whenever they want. New apps will be on the new stuff. Old apps can upgrade whenever. New apps can opt into the RestApi if for some reason they want to do that too.

For me, the big win here is for our new users. Currently folks are always troubled by RestApi trailing /staging and /production path parts on URL and I don't blame them it bugs me too! We should get this in, non breaking, ASAP.

@exalted
Copy link

exalted commented May 28, 2020

I am a tad puzzled, because I remember having read this on Slack on May 13th 2020:

ryan: just want to post an FYI for everyone since we've had a lot of questions about api gateway HTTP APIs lately! while we do have sunrise support for them via architect/macro-http-api, i think it bears noting that reason we did http apis as a macro and not as core architect is because we've seen a lot of thrash – breaking changes, payload signature changes, etc. – and not enough service integration support in http apis to consider them stable. so i just wanted to let y'all know that you should adjust your expectations accordingly!

  • right now we only consider api gateway REST APIs to be stable
  • despite being GA as of recently, we do NOT yet feel HTTP APIs are stable

https://architecture-as-text.slack.com/archives/C6BGT0D08/p1589383266149600?thread_ts=1589383266.149600

Now, only after 15 days, all the sudden HTTP APIs are good to go? (I personally I am okay to upgrade to HTTP APIs, don't get me wrong, but curious at the same time…)


FWIW, I too would like to see HTTP being the default also from a configuration perspective (promoting less additional config and more convention/default), so here's my take on how I'd see that happen:

What would happen to existing (REST) apps when HTTP becomes the new default:

Infer REST as @ryanblock suggested and nothing changes:

@http
get /foo

As an existing app what if I want to opt-in for the new HTTP (since I opt-in explicitly the fact that my app breaks is my responsibility and I'll make sure to fix it before deploying in production):

@http
get /foo

@aws
apigateway http  # <-- Once deployed, no longer needed (more about this later)

What would happen to new apps when HTTP becomes the new default:

@http
get /foo

Detect this is a new app (i.e. infer no previous REST API Gateway is present), so create HTTP.


About "once deployed, no longer needed" above:

Since opting in is a one-time only thing, perhaps it could be part of the arc deploy CLI rather than the config file? I am thinking something like:

arc deploy production --apigateway=http

… or —with a more ambitious take— perhaps even arc deploy production --migration=apigateway-http if you think this --migrate argument being a valid path for possible future opt-in-to-new-defaults.


Although in both config and CLI argument approaches rest could be an option where http is given (as value) in order to "go back" to previous configuration for whatever reason or to create a REST API even if it's a brand new app, I personally think from a maintainability perspective perhaps it's good to take a bolder approach and make opting [back] to REST as hard as possible (as in: Architect promotes HTTP APIs, period. REST API is a thing of the past…)

@ryanblock
Copy link
Member Author

ryanblock commented May 28, 2020

We've been evaluating HTTP APIs since last summer, and in contact with the API Gateway team throughout the process. At the time of the Slack conversation you linked, we had last checked in on HTTP APIs a number of weeks prior, and as I recall, we were a few weeks downstream of a post-GA breaking change (the nature of which I can't remember which right now, @brianleroux may). Also we'd seen a number of complaints about HTTP APIs in the Architect Slack in the intervening weeks. As such, we felt the need to set expectations within the community based on what we'd been seeing – especially as it pertained to what we, as maintainers, were willing to be expected to support.

Fast forward: as I feel is part of my responsibility to the project, I once again checked in on HTTP APIs to see how that product has been developing. I was spurred to do this partly because we hadn't heard complaints about HTTP APIs lately (perhaps in part due to said expectation setting?); because I hadn't noticed or heard of any breaking changes of late; because users have continued to struggle with the REST API stage path prefixes; and because, as mentioned, that's part of the job.

While admittedly anecdotal (and downstream of some of the things I just mentioned, about HTTP API complaints tapering off), things in HTTP API land were feeling stable, save for a few console bugs, and API import/export issues. In my research this week I also discovered that we have what we need from a service integration standpoint to achieve feature parity with current REST APIs (namely, S3 /_static support), which we did not feel we had before. Additionally, I was able to come up with a forwards and backwards compatible path for Architect, which addressed an ongoing concern we'd had about how to de-risk the eventual adoption of HTTP APIs as default. This gave me enough justification to begin discussing the promotion of HTTP APIs to default.

After some internal discussion, including deliberation on what we, as core maintainers, are ready to declare we'll support, I decided to seed this conversation. So from my perspective, this wasn't sudden, per se (although I take your point).

Re. migration, that makes sense – I think we'll probably need to have something in the @aws pragma to enshrine this change, but I agree that as a one-time change for existing users, it would make sense to use workflows to enact that change, and not the manifest.

Re. backwards compat, I don't see an issue with continuing to maintain our existing REST API code paths – they've changed basically not at all for years, so we can take things as they come but I don't anticipate much reason to hard deprecate anything in the near term.

@exalted
Copy link

exalted commented May 28, 2020

@ryanblock I hope to have not sounded as if I was criticizing apparently sudden change of thoughts: I was curious, is all… I appreciate all the work you're putting into Architect. Thank you!

@brianleroux
Copy link
Member

brianleroux commented May 28, 2020

I really like the idea of making this upgrade a one time CLI flag. Adding more stuff to the @aws pragma/architect schema is somewhat more costly long term as it spreads the code between a bunch of modules. This would keep it additive and local to architect/deploy. Worth considering!

@ryanblock
Copy link
Member Author

ryanblock commented May 29, 2020

@exalted all good, it's important to know when and why things change!

@filmaj
Copy link
Member

filmaj commented Jun 26, 2020

My view on this:

  • 👍 to a one-time upgrade flag via the CLI. This is probably my biggest concern with this move - how do we support users moving from REST to HTTP? And would we support going from HTTP back to REST?
  • With that in mind, I like the option to explicitly define whether to use REST or HTTP via the @aws pragma over the @http pragma. Keeping an eye long-term on having arc support cloud vendors other than AWS, feels like this option is AWS-specific and so it belongs in cloud-vendor-specific sections inside the parser. I understand @brianleroux's concern about not trying to add more stuff to the arc parser, but I have a feeling there are users out there who have built REST-based extensions and so we'll need a way to expose REST vs HTTP to users.

Other than that, I'm excited for the 70% price reduction 😄

@ryanblock
Copy link
Member Author

ryanblock commented Jun 28, 2020

Heads up! First cut of this just landed in @architect/package 2.0.0@RC + @architect/deploy 1.9.0@RC – can test independently of Architect with npm i @architect/deploy@RC and npx arc-deploy.

There's still more work to do, but this now supports:

  • deploy --apigateway rest|http
  • @aws apigateway rest|http

Unless you manually set one of those settings, whatever your API already is, it will continue to be that same API type.

Have some more hardening to do before I'm ready for everyone to jump in on testing, but please do feel free (and, of course, report those bugs).

Will check back soon with additional progress, including full Architect Functions support.

PRs here:

@ryanblock ryanblock added this to the 6.6.0 milestone Jun 29, 2020
@ryanblock
Copy link
Member Author

ryanblock commented Jul 2, 2020

New consideration surfaced in #900: $default behaves differently than /{proxy+} in that it catches all methods at the root.

This means Sandbox will need to assume the default behavior of HTTP APIs with backwards compatibility for REST APIs.

@ryanblock
Copy link
Member Author

ryanblock commented Sep 16, 2020

Shipping tomorrow!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
@deploy @architect/deploy enhancement @package @architect/package
Development

No branches or pull requests

5 participants