In praise of Microsoft
-
We see a whole load of posts about how Microsoft sucks. Well, this is praise for them. In my day to day, I do a load of API design work using OpenAPI. Frankly, while OpenAPI is great, the tooling and development of it is less than amazing. It's cumbersome, and it doesn't promote easy reuse. Well, Microsoft has produced something called TypeSpec[^] which makes API design an absolute delight. It's now supplanting my tool of choice (SwaggerHub). So, I want my APIs to return all records on an endpoint and I want them to have common statuses on the return. Well, if I do this:
op all(): {
@statusCode statusCode: 200;
@body records: T[];
} | {
@statusCode statusCode: 400;
@body error: Error;
} | {
@statusCode statusCode: 401;
} | {
@statusCode statusCode: 403;
};Then I can do this:
@route("/organizations")
interface Organizations {
op all is all;
}Well, what does that look like when I produce my OpenAPI design out of this?
openapi: 3.0.0
info:
title: Some title
version: 0.0.0
tags: []
paths:
/organizations:
get:
operationId: Organizations_all
parameters: []
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Organization'
'400':
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Access is unauthorized.
'403':
description: Access is forbidden
components:
schemas:
Organization:
type: object
required:
- id
- name
- apiKey
properties:
id:
type: string
format: uuid
description: The unique identifier for the organisation
name:
type: string
description: The name of the organisation
servers:- url: https://api.my.services
description: Single Endpoint
variables: {}
All in all, that's pretty darn awesome and it allows me to produce consistent API responses with the minimum of fuss.
- url: https://api.my.services
-
We see a whole load of posts about how Microsoft sucks. Well, this is praise for them. In my day to day, I do a load of API design work using OpenAPI. Frankly, while OpenAPI is great, the tooling and development of it is less than amazing. It's cumbersome, and it doesn't promote easy reuse. Well, Microsoft has produced something called TypeSpec[^] which makes API design an absolute delight. It's now supplanting my tool of choice (SwaggerHub). So, I want my APIs to return all records on an endpoint and I want them to have common statuses on the return. Well, if I do this:
op all(): {
@statusCode statusCode: 200;
@body records: T[];
} | {
@statusCode statusCode: 400;
@body error: Error;
} | {
@statusCode statusCode: 401;
} | {
@statusCode statusCode: 403;
};Then I can do this:
@route("/organizations")
interface Organizations {
op all is all;
}Well, what does that look like when I produce my OpenAPI design out of this?
openapi: 3.0.0
info:
title: Some title
version: 0.0.0
tags: []
paths:
/organizations:
get:
operationId: Organizations_all
parameters: []
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Organization'
'400':
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Access is unauthorized.
'403':
description: Access is forbidden
components:
schemas:
Organization:
type: object
required:
- id
- name
- apiKey
properties:
id:
type: string
format: uuid
description: The unique identifier for the organisation
name:
type: string
description: The name of the organisation
servers:- url: https://api.my.services
description: Single Endpoint
variables: {}
All in all, that's pretty darn awesome and it allows me to produce consistent API responses with the minimum of fuss.
In my case, most of my posts against Microsoft are mostly in the insider news and more in joke, sacarsm mode than real rants. At the end of the day I am still using it and will still use it (at least at job)
M.D.V. ;) If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about? Help me to understand what I'm saying, and I'll explain it better to you Rating helpful answers is nice, but saying thanks can be even nicer.
- url: https://api.my.services
-
We see a whole load of posts about how Microsoft sucks. Well, this is praise for them. In my day to day, I do a load of API design work using OpenAPI. Frankly, while OpenAPI is great, the tooling and development of it is less than amazing. It's cumbersome, and it doesn't promote easy reuse. Well, Microsoft has produced something called TypeSpec[^] which makes API design an absolute delight. It's now supplanting my tool of choice (SwaggerHub). So, I want my APIs to return all records on an endpoint and I want them to have common statuses on the return. Well, if I do this:
op all(): {
@statusCode statusCode: 200;
@body records: T[];
} | {
@statusCode statusCode: 400;
@body error: Error;
} | {
@statusCode statusCode: 401;
} | {
@statusCode statusCode: 403;
};Then I can do this:
@route("/organizations")
interface Organizations {
op all is all;
}Well, what does that look like when I produce my OpenAPI design out of this?
openapi: 3.0.0
info:
title: Some title
version: 0.0.0
tags: []
paths:
/organizations:
get:
operationId: Organizations_all
parameters: []
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Organization'
'400':
description: The server could not understand the request due to invalid syntax.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Access is unauthorized.
'403':
description: Access is forbidden
components:
schemas:
Organization:
type: object
required:
- id
- name
- apiKey
properties:
id:
type: string
format: uuid
description: The unique identifier for the organisation
name:
type: string
description: The name of the organisation
servers:- url: https://api.my.services
description: Single Endpoint
variables: {}
All in all, that's pretty darn awesome and it allows me to produce consistent API responses with the minimum of fuss.
To be honest, I don't understand what the point of that TypeSpec is, because it doesn't generate C# REST API's. :laugh:
Latest Articles:
A Lightweight Thread Safe In-Memory Keyed Generic Cache Collection Service A Dynamic Where Implementation for Entity Framework - url: https://api.my.services
-
To be honest, I don't understand what the point of that TypeSpec is, because it doesn't generate C# REST API's. :laugh:
Latest Articles:
A Lightweight Thread Safe In-Memory Keyed Generic Cache Collection Service A Dynamic Where Implementation for Entity Framework