Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Evaluating the State of APIs - Comparing REST, ...

Evaluating the State of APIs - Comparing REST, GraphQL, gRPC

Spencer Schneidenbach

January 12, 2023
Tweet

More Decks by Spencer Schneidenbach

Other Decks in Programming

Transcript

  1. What we need to talk about • History of APIs

    • Use cases • Ease of adoption/use • Performance • Team constraints @schneidenbach
  2. SOAP • XML over HTTP (typically) • Contained request/response in

    “envelope” • Highly structured @schneidenbach
  3. <definitions name = "HelloService" targetNamespace = "http://www.examples.com/wsdl/HelloService.wsdl" xmlns = "http://schemas.xmlsoap.org/wsdl/"

    xmlns:soap = "http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns = "http://www.examples.com/wsdl/HelloService.wsdl" xmlns:xsd = "http://www.w3.org/2001/XMLSchema"> <message name = "SayHelloRequest"> <part name = "firstName" type = "xsd:string"/> </message> <message name = "SayHelloResponse"> <part name = "greeting" type = "xsd:string"/> </message> <portType name = "Hello_PortType"> <operation name = "sayHello"> <input message = "tns:SayHelloRequest"/> <output message = "tns:SayHelloResponse"/> </operation> </portType> https://www.tutorialspoint.com/wsdl/wsdl_quick_guide.htm @schneidenbach
  4. Problems • Incongruent implementations across platforms • Heavy/noisy • Strictly

    XML based • Very sensitive to envelope/data construction format • nil/null vs empty string @schneidenbach
  5. JSON to the rescue! REST to the rescue! { "actor":

    { "name": "Tom Cruise", "age": 56, "Born At": "Syracuse, NY", "Birthdate": "July 3 1962", "photo": "https://jsonformatter.org/img/tom-cruise.jpg" } } https://codeblogmoney.com/json-example-with-data-types-including-json-array/ @schneidenbach
  6. Resource identification Uniform Interface constraint Content-Type: application/json Resource manipulation with

    representations Self-descriptive Hypermedia as the engine of application state (HATEOAS) GET /employees/1234 PUT /employees/1234 @schneidenbach
  7. What is a RESTful API? RESTful API == an API

    that follows REST architecture Term has been sort of co-opted REST != JSON REST != HTTP Lots of people say “REST API” when they really mean HTTP JSON API @schneidenbach
  8. REST Strengths • Ubiquitous, universally understood • Easy to start

    up in your favorite library • Hypermedia can be a boon… if implemented well/correctly • JSON/XML easy to read and descriptive @schneidenbach
  9. REST Weaknesses • Over/under-fetching • Design-first - you have to

    well understand the use cases for your API ahead of time • Most APIs are not purely RESTful - not a bad thing, but is a thing • No built-in spec - lots can be generated/created after the fact (OpenAPI for instance) but not perfect • Versioning tricky @schneidenbach
  10. When we built Facebook’s mobile applications, we needed a data-fetching

    API powerful enough to describe all of Facebook, yet simple enough to be easy to learn and use by our product developers. https://engineering.fb.com/2015/09/14/core-data/graphql-a-data-query-language/ @schneidenbach
  11. What they had • REST-based APIs were WAY too chatty

    • HTML views pushed up to the client weren’t mobile-optimized @schneidenbach
  12. GraphQL has… • Strong spec • Predictable requests/responses • No

    over/under-fetching • Strongly typed • Nearly self-documenting • First-class deprecation @schneidenbach
  13. { "invoices": [ { ... }, { ... } ]

    } GET /customers/1234/ invoices GET /customers/ 1234 ?expand=invoices Within the parent object Related resource retrieval strategies As a separate request Using an expand parameter @schneidenbach
  14. GraphQL weaknesses • Less ubiquitous from a framework/platform perspective •

    Caching more difficult • Steep learning curve for developers used to REST • Narrower use cases • Not as widely used @schneidenbach
  15. gRPC is based on many years of experience in building

    distributed systems. With the new framework, we want to bring to the developer community a modern, bandwidth and CPU ef fi cient, low latency way to create massively distributed systems that span data centers, as well as power mobile apps, real-time communications, IoT devices and APIs. https://developers.googleblog.com/2015/02/introducing-grpc-new-open-source-http2.html?m=1 @schneidenbach
  16. HTTP/2 • Support for multiplexing • Supports streams of data

    first-class • Multiple requests per one connection • Serialized in Protobuf format by default • Encryption NOT optional @schneidenbach
  17. .proto file syntax = "proto3"; service Greeter { rpc SayHello

    (HelloRequest) returns (HelloReply); } message HelloRequest { string name = 1; } message HelloReply { string message = 1; } @schneidenbach
  18. Advantages of gRPC • Strict contracts • Designed with performance

    in mind - less data over the wire and less connection overhead • Clients and servers can generate code from .proto files • Also helps enable polyglot development @schneidenbach
  19. Challenges with gRPC • Not as widely known/adopted as REST/GraphQL

    • Bound to HTTP/2 (though this is less of an issue than it was when introduced) • No human readable formatting w/o helpers • Strict contracts @schneidenbach
  20. What we need to talk about • Use cases •

    Ease of adoption/use • Team constraints • Performance @schneidenbach
  21. Integration APIs • Lots of potential consumers with potentially different

    platforms… and team skills • Ease of use/time to “make magic happen” is critical @schneidenbach
  22. Backends for frontends • Aka, data aggregation services for mobile/web

    • Homogenous data requirements (CRUD?) Low volume of requests? Skip BFF, go straight REST • Lots of different data sources to aggregate? GraphQL good for that use case • Clients need data in a wide variety of shapes? GraphQL perfect • Performance as a first class feature? GraphQL/gRPC @schneidenbach
  23. Microservices • Just starting out? Go with what you know

    • Huge volume of requests/transactions? Latency/bandwidth critical? gRPC • Humdrum moving of data back and forth with no particular need for high performance? Probably REST… • …or maybe a message queue? • Lots of services needing different shapes of data? Look at GraphQL @schneidenbach
  24. What we need to talk about • Use cases •

    Ease of adoption/use • Team constraints • Performance @schneidenbach
  25. Ease of adoption • REST wins hands down, but that

    isn’t the end all be all @schneidenbach
  26. What we need to talk about • Use cases •

    Ease of adoption/use • Performance • Team constraints @schneidenbach
  27. Performance • REST as a straight CRUD service is gonna

    be pretty fast on any framework • GraphQL is designed to be less bytes on return trip. But… • GraphQL, depending on its level of aggregation, is data-first, optimize-second. • gRPC was designed with high performance in mind, which is why it uses HTTP/2 • Buuuuuut… performance is relative. How fast is fast enough? @schneidenbach
  28. My recommendation would be: measure, fi nd bottlenecks and fi

    x the ones that matter. https://samsaffron.com/archive/2011/03/30/How+I+learned+to+stop+worrying+and+write+my+own+ORM @schneidenbach
  29. What we need to talk about • Use cases •

    Ease of adoption/use • Performance • Team constraints @schneidenbach
  30. Team constraints • What kinds of devs is your team

    composed of? • Is the new technology worth the overhead of “learning a new thing”? • This is such a cultural question that it’s hard to answer here, but it’s a consideration to make @schneidenbach
  31. No matter what • Versioning/deprecation strategy • Documentation • Uptime

    guarantees • Quality control/testing • Tooling/SDKs @schneidenbach