Reigniting the API Description Wars with TypeSpec and the Next Generation of API Languages - Gareth Jones, Microsoft
•Télécharger en tant que PPTX, PDF•
0 j'aime•17 vues
A presentation given by Gareth Jones, API Architect at Microsoft, at our 2024 Austin API Summit, March 12-13. Session Description: Didn't the API description wars end in 2017 when we all agreed that OAS was the way forward? Yes, and yet how satisfied with your API descriptions are you? Are they thousands of lines of hard to read yaml or JSON? When someone makes a change, is it easy to review for correctness and completeness? Do visual tools make this easier? Do they support change management? I'll make the case that the next generation of more abstract DSLs for defining APIs such as Smithy from Amazon and TypeSpec, open sourced by Microsoft, move us back to a more intentional approach to design and give us the opportunity to highlight the business characteristics that matter most at design-time.
Recommandé
Recommandé
Contenu connexe
Similaire à Reigniting the API Description Wars with TypeSpec and the Next Generation of API Languages - Gareth Jones, Microsoft
Similaire à Reigniting the API Description Wars with TypeSpec and the Next Generation of API Languages - Gareth Jones, Microsoft (20)
Plus de Nordic APIs
Plus de Nordic APIs (20)
Dernier
Dernier (20)
Reigniting the API Description Wars with TypeSpec and the Next Generation of API Languages - Gareth Jones, Microsoft
- 1. Reigniting the API Description Wars with TypeSpec and the Next Generation of API Languages Gareth Jones Architect Microsoft Corporation @garethj_msft Austin API Summit 2024 #AustinAPISummit #nordicapis
- 3. ? RAML
- 7. Co- design Business involveme nt SDKs Docs Mocks Runtime Validat ion Governanc e Low code Lint er
- 9. 0 500000 1000000 1500000 2000000 2500000 0 5000 10000 15000 20000 25000 API Operations vs OAS Lines of Code Operations LOC OAS
- 10. Co- design Business involveme nt SDKs Docs Mocks Runtime Validat ion Governanc e Low code Lint er
- 13. openapi: 3.0.0 info: title: Weather Service version: 2006-03-01 tags: [] paths: /cities: get: operationId: CityOps_ListCities parameters: - name: nextToken in: query required: false schema: type: string - name: pageSize in: query required: false schema: type: integer format: int32 responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CitySummaries' /cities/{cityId}/forecast: get: operationId: ForecastOps_GetForecast parameters: - name: cityId in: path required: true schema: $ref: '#/components/schemas/CityId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Forecast' /cities/{cityId}: get: operationId: CityOps_GetCity parameters: - name: id in: path required: true schema: $ref: '#/components/schemas/CityId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/City' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/NoSuchResource' /getCurrentTime: get: operationId: time_GetTime parameters: [] responses: '200': description: The request has succeeded. content: application/json: schema: type: string format: date-time components: schemas: City: type: object required: - cityId - coordinates properties: cityId: $ref: '#/components/schemas/CityId' coordinates: $ref: '#/components/schemas/CityCoordinates' CityCoordinates: type: object required: - latitude - longitude properties: latitude: type: number longitude: type: number CityId: type: string pattern: ^[A-Za-z0-9 ]+$ CitySummaries: type: array items: $ref: '#/components/schemas/CitySummary' CitySummary: type: object required: - cityId - name properties: cityId: $ref: '#/components/schemas/CityId' name: type: string Forecast: type: object required: - chanceOfRain properties: chanceOfRain: type: number NoSuchResource: type: object required: - resourceType properties: resourceType: type: string allOf: - $ref: '#/components/schemas/TypeSpec.Http.NotFoundResponse' TypeSpec.Http.NotFoundResponse: type: object description: The server cannot find the requested resource.
- 14. $version: "2" namespace example.weather @paginated(inputToken: "nextToken", outputToken: "nextToken", pageSize: "pageSize") service Weather { version: "2006-03-01" resources: [ City ] operations: [ GetCurrentTime ] } resource City { identifiers: { cityId: CityId } properties: { coordinates: CityCoordinates } read: GetCity list: ListCities resources: [ Forecast ] } resource Forecast { identifiers: { cityId: CityId } properties: { chanceOfRain: Float } read: GetForecast } @pattern("^[A-Za-z0-9 ]+$") string CityId @readonly operation GetCity { input := for City { @required $cityId } output := for City { @required @notProperty name: String @required $coordinates } errors: [ NoSuchResource ] } // This structure is nested wihin GetCityOutput. structure CityCoordinates { @required latitude: Float @required longitude: Float } @error("client") structure NoSuchResource { @required resourceType: String } @readonly @paginated(items: "items") operation ListCities { input := { nextToken: String pageSize: Integer } output := { nextToken: String @required items: CitySummaries } } list CitySummaries { member: CitySummary } @references([ { resource: City } ]) structure CitySummary { @required cityId: CityId @required name: String } @readonly operation GetCurrentTime { output := { @required time: Timestamp } } @readonly operation GetForecast { input := for Forecast { // "cityId" provides the only identifier for the resource since // a Forecast doesn't have its own. @required $cityId } output := for Forecast { $chanceOfRain } } resource City { identifiers: { cityId: CityId } properties: { coordinates: CityCoordinates } read: GetCity list: ListCities resources: [ Forecast ] }
- 15. • import "@typespec/http"; import "@typespec/http"; • using Http; • @service({title: "Weather Service", version: "2006-03- 01"}) • namespace example.weather; • model City{ • @key cityId: CityId; • coordinates: CityCoordinates; • } • model Forecast { • chanceOfRain: float; • } • @route("/cities") • interface CityOps { • @route("{cityId}") • @get GetCity(@path cityId: CityId): City | NoSuchResource; • @get ListCities(@query nextToken?: string, @query pageSize?: int32): CitySummaries; • } • @route("/cities/{cityId}/forecast") • interface ForecastOps { • @get GetForecast(@path cityId: CityId): Forecast; • } • @route("/getCurrentTime") • interface time { • @get GetTime(): offsetDateTime; • } • @pattern("^[A-Za-z0-9 ]+$") • scalar CityId extends string; • model CityCoordinates { • latitude: float; • longitude: float; • } • model CitySummary { • cityId: CityId; • name: string; • } • model CitySummaries is CitySummary[]; • @error model NoSuchResource extends NotFoundResponse{ • resourceType: string; • } model City{ @key cityId: CityId; coordinates: CityCoordinates; } model Forecast { chanceOfRain: float; } @route("/cities") interface CityOps { @get ListCities(@query nextToken?: string, @query pageSize?: int32): CitySummaries; @route("{cityId}") @get GetCity(@path cityId: CityId): City | NoSuchResource; }
- 16. • import "@typespec/http"; import "@typespec/http"; • using Http; • @service({title: "Weather Service", version: "2006-03- 01"}) • namespace example.weather; • model City{ • @key cityId: CityId; • coordinates: CityCoordinates; • } • model Forecast { • chanceOfRain: float; • } • @route("/cities") • interface CityOps { • @route("{cityId}") • @get GetCity(@path cityId: CityId): City | NoSuchResource; • @get ListCities(@query nextToken?: string, @query pageSize?: int32): CitySummaries; • } • @route("/cities/{cityId}/forecast") • interface ForecastOps { • @get GetForecast(@path cityId: CityId): Forecast; • } • @route("/getCurrentTime") • interface time { • @get GetTime(): offsetDateTime; • } • @pattern("^[A-Za-z0-9 ]+$") • scalar CityId extends string; • model CityCoordinates { • latitude: float; • longitude: float; • } • model CitySummary { • cityId: CityId; • name: string; • } • model CitySummaries is CitySummary[]; • @error model NoSuchResource extends NotFoundResponse{ • resourceType: string; • } model City{ @key cityId: CityId; coordinates: CityCoordinates; } model Forecast { chanceOfRain: float; } @route("/cities/{cityId}/forecast") interface ForecastOps { @longRunning(stepwise, "/operations/{operationId}") @get GetForecast(@path cityId: CityId): Forecast | NoSuchResource; }
- 18. • Investigate new languages • Contribute to moonwalk • Give us feedback on TypeSpec https://typespec.i
Notes de l'éditeur
- Good morning. My name’s Gareth Jones and I’m an Architect on the Microsoft Graph team. I’d like to spend the next half an hour talking about our journey to Open API and what the next steps in that journey might be. I’ll be the first to admit that my title has an element of clickbait about it but we’ll get to that in a few minutes, OK?
- I think wise folks have been debating how computing machines should talk to each other since long before computers even existed. I think this newspaper article appeared in the late 1800s. Let’s take a whistlestop tour of how we got to today. In the 1990s, we went through dark days of CORBA, talking to stateful objects over the wire, but it did make us realize we needed a way to describe interfaces independent of implementations and so IDL was born – A WELL KNOWN INTERFACE DESCRIPTION LANGUAGE By the mid 2000s we’d arrived at web services based on XML and SOAP, and by 2007 we had WSDL, the first widely used XML-based IDL. I can hear some of you wincing at the memory.
- But by the turn of the decade our pointy brackets were being overtaken by braces and JSON was the new hotness, and a new wave of API description languages were emerging, each with a different take on what aspects of APIs were key, and their own set of loyal fans. 2011 Swagger April 2013 API Blueprint September 2013 RAML So our nascent community formed, and we started to have API conferences and debate the merits of these things
- What were those early API conferences like? Was it a rarified and respectful exchange of ideas? Maybe sometimes a bit of a feisty meeting of minds? I don’t think it was too often like this, but maybe once in a while? But this period, gentle colleagues, is what is hyperbolically referred to as the API Description Wars. And we did have some entertainingly competitive cross-pollination of ideas. Personally, I’m inclined to think tech companies are at their best when their ideas are closely linked to their competitiveness
- However, eventually, we largely coalesce around Swagger and make the move to the Open API Initiative and Open API Specification We build our community more, it’s widely adopted, and tool vendors give great support to the standard.
- And we’ve been iterating and improving our OAS story and tools ever since. I think at this point, we’re all clear that OAS is an amazing enabler for toolchains and interop for our APIs. Just as a simple example, if you look at the quality and breadth of SDKs that are available for almost any API now, it’s night and day from where we were five years ago. Generated SDKs used to be pretty hard to use and often missing details from the underlying API that customers needed. We had to put in a lot of manual effort to get them to a usable state. Now we’re in a position where many OAS descriptions are detailed and accurate, and I think you can see from the SDK vendors here this qeek, and our own recently open-sourced SDK tooling, Kiota, that that part of our ecosystem is flourishing.
- So, we got to OAS and now our API world is perfect? Toolchains, interop, design tools, linting tools, reusable data validation with JSON schema, repositories, plugins to low-code tools, SDKs for every language you can think of. I’ve spread them out on a bit of a spectrum here, and on the right, it seems like more technical, automation-centric scenarios are well-catered for. I’m going to come back to the left side, but I want to motivate it first.
- Let’s talk about scale – If you caught Mandy’s talk yesterday, you’ll know we’re facing a lot of challenges of extreme scale at Microsoft, but honestly, I think it’s pretty directional for our industry. APIs are getting larger in every dimension More protocols, not just REST, perhaps we need gRPC or maybe eventing with Async APIs? More endpoints – new features keep on coming More detail – SDKs should have all the options and enable 100% of API functionality More versions – we all have to deal with back compat once we get customers More people – James talked about teams of 10,000 yesterday
- Looking at some real sizes for common APIs comparing number of operations with the size of the OAS file in lines of code The lines aren’t too out of whack, number of operations in an API scales roughly linearly with lines of code But at almost two orders of magnitude! T That’s just too high a ratio for sensible design and governance experiences that want to focus on what the api does and that consistent approaches are being taken and this size and complexity, business folks just switch off.
- So the human experience for the things on the left side of my spectrum ends up a bit tiring All those details and accurate metadata that makes for a high-quality toolchain makes the human aspects of design and governance a challenge Quick straw poll Put your hands up if you work with OAS files in your job. Leave you hand up if you enjoy creating and reviewing OAS files? Who finds it a bit overwhelming? It’s OK, you’re not betraying the API conference cause – we’re all human And admitting it is the first step towards change
- As usual, when we’ve got a problem in software around overwhelming detail, we can get a lot of benefit from applying abstraction to lift us out of the detail, and then apply standard patterns when we need to put the detail layer back in. It’s all about SEMANTIC COMPREHENSION compared with OPERATIONAL DETAIL Both are key, but at different points in the API lifecycle I think it’s important to recognize that abstraction doesn’t just provide clarity by removing detail. It also frees us from being locked into discussion of that detail and opens the conversation up to broader topics with stakeholders. As we’re not debating the fine detail of the cat’s fur and whiskers, we might discuss that it seems to be stretching, and stumble onto a discussion about whether other handsome cat poses are required. Or whether the cat should even have been disturbed from sleep in the first place. It’s a powerful tool for making space.
- I’m going to touch on three tools: TypeSpec from Microsoft, Smithy from Amazon and moonwalk, the next generation of OAS
- Let’s start with looking at an OAS file describing a trivial API – a weather forecast system I don’t expect you to read this, just grasp the rough size. I’ve highlighted that there are four endpoints to this API, They let me list cities, get details and the forecast for a city and find the current time. It’s about 100 lines and there’s a lot of boilerplate.
- Here’s a Smithy description of the same API. You see I’ve picked out the same four endpoints, but they’re more abstract in Smithy – this definition could work for gRPC or REST for example. We’d just need to add a standard HTTP binding. Let’s look at a bit of the syntax so you get an idea We explicitly define the identifiers that can be used as keys in a model, then add other properties, We list the available operations that use this resource, then finally that a City has a Forecast as a sub-resource.
- Now here’s TypeSpec definition. Again, this one has the same endpoints, and you can see it’s really terse . And here’s that same callout for the resource definitions with the key identified – these could be reused across protocols. I’ve included HTTP binding directly inline, even though the file is still tiny You can see that in one interface I’m able to specify two paths from the OAS – the /cities and the /cities/cityId So now I could simply compile this with my OAS emitter to produce that very complete and detailed OAS file. In fact, that’s how I got it.
- Now can we add some deeper metadata? Let’s say our get forecast endpoint needs to run for a couple of seconds for some reason. We have a standard pattern for long-running operations, involving returning a 202, a location header and providing an operations endpoint to poll for the status of the operation with a well-known signature. I can announce that I’m using that “stepwise” named pattern really tersely and provide the URL to poll. Even the URL is optional if I’m using the standard URL. That’s pretty clear to any reader without making the file busy with the implementation detail. So, seems like we’re back in the world of having a little healthy competition! I suggest you go back and check out my colleague Mandy’s more detailed talk once the recordings are up on the web or have a look at typespec.io
- What about moonwalk? What’s the next version of OAS bringing to the table? Well, it’s all very much in the early stages of development, but there are five areas where the team are working. Perhaps the most important for today’s discussion is direct support for semantics. OAS descriptions are great at saying what an API’s shape is, but don’t have a lot to say today about HOW it should be used. TypeSpec and Smithy both have simple mechanisms for creating easily packaged reusable libraries of decorators or traits to label your API with HOW metadata as we saw with the long-running operation example. Moonwalk should provide a way for that information to flow all the way through your toolchains, so it’s more than just a note at design time. Reference Semantics provide purpose. It is not sufficient to describe the mechanics of an API without also describing its semantics, whether the consumer is a human or an AI. Semantics join the what (… does this do?) and the why (… does this matter?) to the how (… does this work?).OpenAPI has helped people build better APIs faster, and the ecosystem of tooling continues to deliver more value year after year. What is new today in 2023 is the rise of a new kind of API consumer—generative AI. LLMs can process OpenAPI descriptions and then use that API to solve problems. With generative AI’s ability to understand natural language, OpenAPI can help bring the power of APIs to non-developers with a level of accessibility never seen before. To fully realize this potential, API producers should decorate their mechanical descriptions of HTTP requests with details that convey the meaning and purpose of those API operations. This, in turn, helps both people and LLMs to achieve better results. To say this another way, people have been using squishy, natural language to talk to each other for centuries, and we’ve used crunchy, programming languages to talk to machines for decades. LLMs bridge the squishy and the crunchy worlds, which means that a huge number of people can use APIs who could not before. Regardless of your opinion of generative AI, from over-hyped to world-changing, we can expect that many people will be using OpenAPI to drive AI-based API consumers. If OpenAPI does not step up to address the needs of that community, they will find alternatives. 🌒 Signature please! An API represents a set of functions, each of which describes a client-oriented purpose. A function is identifiable by its signature, which correlates to a set of HTTP interactions. Moonwalk places this concept at its center.Any HTTP API is always a means to some end. API consumers prefer to reuse existing functionality, and ideally they can learn about that functionality in terms that are most natural to them. That a PUT/PATCH/DELETE returns a 200 or a 204 is an implementation detail that pales in comparison to the function it performs for the client. Today there are limited ways to express the signature of an API function in OpenAPI. A pathItem can’t use query parameters to distinguish operations. There can only be one operation per HTTP method. These are artificial constraints on the signature of the API functions due to the lack of a formal definition of the unique signature. Past efforts in OpenAPI have focused on enabling developers to describe HTTP APIs. This reprioritizes them so that developers can use OpenAPI to define API functions with unique signatures that then map each signature to HTTP mechanics. 🌕 Inclusion needs a big tent: Moonwalk aspires to describe all HTTP-based APIs. While it remains neutral on the design aspects of HTTP APIs, it recognizes the importance of having different design styles and opinions.Moonwalk should be able to describe the HTTP APIs that developers may already have as well as to design the APIs they may want to build. It should be able to accurately map the signature of an API function to an actual instance of an HTTP request and response provided by the API. Moonwalk does prefer resource-oriented API styles due to their overwhelming popularity, but it should be possible to describe purely RPC APIs, even when those API signatures are distinguished via HTTP header values or request body values. 🌗 Organization through separation of concerns. For example, the changing shape of an API should move independently of API deployments. API deployments may be secured with different security schemes. API functions’ signatures should not be tightly coupled to content schema formats.To support the growing customer base with diverse needs, the feature count will undoubtedly grow, introducing more complexity. To counterbalance this, we will apply more rigor to the modularization of different aspects of the API description. We will strive to eliminate ambiguity where it currently exists and leverage existing standards to minimize unnecessary novelty. Our goal is to provide a better experience for API description consumers, authors and tooling providers. 🌑 Mechanical upgrading. An important principle of OpenAPI v3 was that it offered a direct upgrade path from v2. Moonwalk carries this forward, which means that it must again be possible to mechanically upgrade to Moonwalk from v3 (and by extension, v2).
- So what am I selling here? We’ve got great tools today for automation and mechanical connectivity of API tools. We’ve got a new generation of tooling just appearing or on the immediate horizon that’s really optimized for human productivity with API design and governance at large scale If your APIs are growing, supporting multiple protocols and adding more detail, and you’re feeling a bit overwhelmed by your OAS files, this is a good way forward.
- So here’s my call to action: Make your API design and governance folks’ lives easier by investigating the new generation of languages Get involved in the moonwalk effort and shape it in the standards process Give us all your feedback on TypeSpec Despite my clickbait talk title, don’t go starting new wars in the community – we’re all committed to improving folks’ experience and we all understand that interop via OAS is key Thank you very much – I’d love to talk to you during the day.