在线时间:8:00-16:00
迪恩网络APP
随时随地掌握行业动态
扫描二维码
关注迪恩网络微信公众号
开源软件名称(OpenSource Name):Urigo/SOFA开源软件地址(OpenSource Url):https://github.com/Urigo/SOFA开源编程语言(OpenSource Language):TypeScript 79.3%开源软件介绍(OpenSource Introduction):The best way to create REST APIs (is GraphQL). Installation
Getting StartedHere's complete example with no dependency on frameworks, but also integratable with any of them: import http from 'http';
import getStream from 'get-stream';
import { createSofaRouter } from 'sofa-api';
const invokeSofa = createSofaRouter({
basePath: '/api',
schema,
});
const server = http.createServer(async (req, res) => {
try {
const response = await invokeSofa({
method: req.method,
url: req.url,
body: JSON.parse(await getStream(req)),
contextValue: {
req,
},
});
if (response) {
const headers = {
'Content-Type': 'application/json',
};
if (response.statusMessage) {
res.writeHead(response.status, response.statusMessage, headers);
} else {
res.writeHead(response.status, headers);
}
if (response.type === 'result') {
res.end(JSON.stringify(response.body));
}
if (response.type === 'error') {
res.end(JSON.stringify(response.error));
}
} else {
res.writeHead(404);
res.end();
}
} catch (error) {
res.writeHead(500);
res.end(JSON.stringify(error));
}
}); Another example with builtin express-like frameworks support import { useSofa } from 'sofa-api';
import express from 'express';
const app = express();
app.use(
'/api',
useSofa({
basePath: '/api',
schema,
})
);
// GET /api/users
// GET /api/messages How it worksSofa takes your GraphQL Schema, looks for available queries, mutations and subscriptions and turns all of that into REST API. Given the following schema: type Chat {
id: ID
text: String
}
type Query {
chat(id: ID): Chat
chats: [Chat]
me: Chat
recentChats: [Chat]
} Routes that are being generated:
Nested data and idea behind ModelsSofa treats some types differently than others, those are called Models. The idea behind Models is to not expose full objects in every response, especially if it's a nested, not first-level data. For example, when fetching a list of chats you don't want to include all messages in the response, you want them to be just IDs (or links). Those messages would have to have their own endpoint. We call this type of data, a Model. In REST you probably call them Resources. In order to treat particular types as Models you need to provide two queries, one that exposes a list (with no non-optional arguments) and the other to fetch a single entity (id field as an argument). The model itself has to have an # Message is treated as a Model
type Query {
messages: [Message]
message(id: ID): Message
}
type Message {
id: ID
# other fields ...
} Provide a ContextIn order for Sofa to resolve operations based on a Context, you need te be able to provide some. Here's how you do it: api.use(
'/api',
useSofa({
basePath: '/api',
schema,
async context({ req }) {
return {
req,
...yourContext,
};
},
})
);
Use full responses instead of IDsThere are some cases where sending a full object makes more sense than passing only the ID. Sofa allows you to easily define where to ignore the default behavior: api.use(
'/api',
useSofa({
basePath: '/api',
schema,
ignore: ['Message.author'],
})
); Whenever Sofa tries to resolve an author of a message, instead of exposing an ID it will pass whole data.
Customize endpoint's HTTP Method, path and response status codeSofa allows you to cutomize the http method, path and response status. For example, in case you need api.use(
'/api',
sofa({
schema,
routes: {
'Query.feed': { method: 'POST' },
},
})
); When Sofa tries to define a route for
You can also specify Custom depth limitSofa prevents circular references by default, but only one level deep. In order to change it, set the api.use(
'/api',
useSofa({
basePath: '/api',
schema,
depthLimit: 2,
})
); Custom execute phaseBy default, Sofa uses api.use(
'/api',
useSofa({
basePath: '/api',
schema,
async execute(args) {
return yourOwnLogicHere(args);
},
})
); Subscriptions as webhooksSofa enables you to run GraphQL Subscriptions through WebHooks. It has a special API to start, update and stop a subscription.
Starting a subscriptionTo start a new subscription you need to include following data in request's body:
After sending it to {
"id": "SUBSCRIPTION-UNIQUE-ID"
} Stoping a subscriptionIn order to stop a subscription, you need to pass its id and hit Updating a subscriptionUpdating a subscription looks very similar to how you start one. Your request's body should contain:
After sending it to {
"id": "SUBSCRIPTION-UNIQUE-ID"
} ExampleGiven the following schema: type Subscription {
onBook: Book
} Let's start a subscription by sending that to {
"subscription": "onBook",
"variables": {},
"url": "https://app.com/new-book"
} In return we get an
OpenAPI and SwaggerThanks to GraphQL's Type System Sofa is able to generate OpenAPI (Swagger) definitions out of it. Possibilities are endless here. You get all the information you need in order to write your own definitions or create a plugin that follows any specification. import { useSofa, OpenAPI } from 'sofa-api';
const openApi = OpenAPI({
schema,
info: {
title: 'Example API',
version: '3.0.0',
},
});
app.use(
'/api',
useSofa({
basePath: '/api',
schema,
onRoute(info) {
openApi.addRoute(info, {
basePath: '/api',
});
},
})
);
// writes every recorder route
openApi.save('./swagger.yml'); OpenAPI (Swagger) with Bearer Authentication import { useSofa, OpenAPI } from 'sofa-api';
const openApi = OpenAPI({
schema,
info: {
title: 'Example API',
version: '3.0.0',
},
components: {
securitySchemes: {
bearerAuth: {
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT',
},
},
},
security: [
{
bearerAuth: [],
},
],
});
app.use(
'/api',
useSofa({
basePath: '/api',
schema,
onRoute(info) {
openApi.addRoute(info, {
basePath: '/api',
});
},
})
);
// writes every recorder route
openApi.save('./swagger.yml'); LicenseMIT © Uri Goldshtein |
2023-10-27
2022-08-15
2022-08-17
2022-09-23
2022-08-13
请发表评论