Tudo o que o sgcREST faz, mapeado no servidor REST e nos seus complementos, no mecanismo de servidor OpenAPI e na família do cliente OpenAPI. Todo recurso funciona igual no Delphi e no C++ Builder, e toda licença entrega o código-fonte completo. As subpáginas de componente ainda não foram publicadas para este lançamento, cada item abaixo é autocontido nesta página.
CORS, estatísticas, tenancy e usuários
Spec-first e code-first
Consuma qualquer API descrita em OpenAPI
Delphi 7 a 13, C++ Builder
O sgcREST é autossuficiente. Ele já vem com o runtime sgcWebSockets Core embutido, então não é um complemento, e roda sobre a biblioteca Indy padrão que acompanha o RAD Studio.
OpenAPI code-first precisa do Delphi XE7 ou posterior. Gerar uma especificação a partir de uma classe Delphi anotada depende do RTTI introduzido no XE7. O servidor REST, os seus complementos e o mecanismo OpenAPI spec-first rodam do Delphi 7 ao 13.
Quatro componentes na página de paleta SGC REST, e três classes de servidor e cliente OpenAPI apenas de código, declaradas nas units sgcHTTP_REST_Server* e sgcHTTP_OpenAPI_*.
| Componente | Classe | Na paleta? | Descrição |
|---|---|---|---|
| Servidor REST | TsgcHTTPRESTServer | Sim | Servidor REST API construído sobre o TsgcHTTPServer, com tratamento de CORS e complementos anexáveis de estatísticas/tenancy. |
| Estatísticas do servidor REST | TsgcHTTPServerStats | Sim | Contadores de requisições, rastreamento de latência, /metrics no formato Prometheus e /health em JSON. |
| Tenancy do servidor REST | TsgcHTTPServer_Tenancy | Sim | Resolução multi-tenant por host, caminho, cabeçalho ou claim JWT. |
| Usuários do servidor REST | TsgcHTTPServer_Users | Sim | Armazenamento local de contas: adicionar, validar, hashear, marcar por papel e persistir usuários. |
| Servidor OpenAPI, Spec-First | TsgcOpenAPIServerHandler | Não, apenas código | Serve uma API a partir de um documento OpenAPI 3.0/3.1 carregado, com validação de requisições. |
| Servidor OpenAPI, Code-First | TsgcOpenAPICodeFirstScanner | Não, apenas código | Gera a especificação OpenAPI a partir de uma classe Delphi anotada com RTTI. Precisa do Delphi XE7+. |
| Cliente OpenAPI | TsgcOpenAPI_Client | Não, apenas código | Cliente de runtime genérico para qualquer endpoint descrito em OpenAPI. |
O TsgcHTTPRESTServer é um descendente de TsgcHTTPServer, então parte dos mesmos bindings e tratamento de TLS que todo servidor HTTP sgc compartilha, e adiciona por cima os extras habituais de uma API REST.
| Recurso | API | Observações |
|---|---|---|
| CORS | CORSOptions (Enabled, AllowOrigins, AllowHeaders, AllowMethods) | Desativado por padrão. Requisições OPTIONS de preflight são respondidas automaticamente quando ativado. |
| Complemento de estatísticas | ServerStats: TsgcHTTPServerStats | Anexe um componente de estatísticas e toda requisição é contada e cronometrada sem tocar nos manipuladores de rota. |
| Complemento de tenancy | Tenancy: TsgcHTTPServer_Tenancy, Tenant | Anexe um componente de tenancy para resolver o tenant do chamador; Tenant lê o resultado para a requisição atual. |
| Contadores de requisições | TotalRequests, Status1xx a Status5xx | No TsgcHTTPServerStats. Contados por classe de status conforme as respostas são enviadas. |
| Latência | LatencyMinMs, LatencyAvgMs, LatencyMaxMs | Rastreada por requisição no TsgcHTTPServerStats, reiniciada com Reset. |
| Endpoint de métricas | GetMetricsText, IsMetricsRequest | Formato de exposição de texto Prometheus 0.0.4, servido em /metrics. |
| Endpoint de saúde | GetHealthJSON, IsHealthRequest | Payload de saúde em JSON servido em /health, inclui UptimeSeconds e ActiveConnections. |
| Estatísticas por endpoint | GetEndpointStats, Endpoints | Um par caminho/contagem por endpoint, para um relatório ou um console administrativo. |
| Resolução de tenant | Resolution, ResolveTenant | No TsgcHTTPServer_Tenancy. Resolve por sufixo de host, segmento de caminho, cabeçalho ou claim JWT. |
| Fontes de tenant | HostSuffix, PathSegmentIndex, HeaderName, ClaimName, DefaultTenant | A fonte lida para o modo Resolution configurado, e o valor padrão quando ela não retorna nada. |
| Resolução personalizada | OnResolveTenant | Sobrescreva ou estenda a lógica de resolução embutida. |
| Contas de usuário | AddUser, DeleteUser, FindUser, ValidateCredentials, SetPassword, EnableUser, UserExists | No TsgcHTTPServer_Users. Credenciais salgadas e hasheadas, nunca retornadas em forma clara. |
| Papéis | AddRole, RemoveRole, UserHasRole, GetUserRoles | Tags de papel livres por conta, verificadas a partir de um manipulador de rota. |
| Enumeração | Count, GetUserCount, GetUserByIndex, GetUsernames | Visões somente leitura para um relatório ou um console administrativo; o hash e o salt da senha nunca são incluídos. |
| Persistência | LoadUsers, SaveUsers, SaveToFile, LoadFromFile, ExportUsers, ImportUsers | Storage.EncryptAtRest criptografa o armazenamento; OnLoadUsers/OnSaveUsers trocam por um backend personalizado. |
| Eventos | OnStats, OnResolveTenant, OnValidateCredentials, OnFindUser, OnException | Um evento por complemento para os casos que a lógica embutida não cobre. |
As duas abordagens alimentam a mesma tabela de rotas e o mesmo contexto de requisição; apenas a origem do documento OpenAPI muda.
| Recurso | API | Observações |
|---|---|---|
| Tabela de rotas | TsgcOpenAPIRouteTable (Add, Match) | Construída a partir da seção paths de uma especificação; associa um verbo e um caminho a um operationId. |
| Contexto de requisição | TsgcOpenAPIServerContext (Request, Response, PathParams, QueryParams) | Uma instância por requisição correspondida, liberada quando a requisição termina. |
| Parâmetros tipados | PathParamAsString, PathParamAsInteger, QueryParamAsString, QueryParamAsInteger, QueryParamAsBoolean | Lê e converte um valor de caminho ou de query em uma única chamada. |
| Acesso ao corpo | BodyAsString, BodyAsJSON, HeaderValue | Analisa o corpo da requisição uma vez e armazena o resultado em cache. |
| Resposta | RespondJSON, RespondError | Escreve um corpo JSON com um código de status, ou um payload de erro estruturado. |
| Ciclo de vida da requisição | BeforeHandle, AfterHandle, HandleException | No TsgcOpenAPIServerHandler. Sobrescreva para adicionar logging, verificações de autenticação ou mapeamento de erro personalizado. |
| Validação | TsgcOpenAPIJSONValidator | Verifica corpos de requisição, parâmetros de query e de caminho contra os JSON Schemas que a especificação declara. |
| Geração de especificação | GenerateSpec, Title, Description, Version, BasePath | No TsgcOpenAPICodeFirstScanner. Produz um documento OpenAPI 3.0 a partir do RTTI de uma classe anotada. |
| Atributos de contrato | sgcServiceContract, sgcRoute, sgcSummary, sgcDescription, sgcTag, sgcResponse | Atributos em nível de classe e método que preenchem a especificação gerada. |
| Atributos de verbo | sgcHttpGet, sgcHttpPost, sgcHttpPut, sgcHttpDelete, sgcHttpPatch, sgcHttpHead, sgcHttpOptions | Declara o verbo HTTP que um método anotado responde. |
| Vinculação de parâmetros | sgcFromPath, sgcFromQuery, sgcFromHeader, sgcFromBody, sgcRequired | Declara de onde cada parâmetro de método é lido. |
| Dispatch | TsgcOpenAPICodeFirstDispatcher (RegisterController, DispatchOperation, IsRegistered) | Invoca diretamente o método anotado registrado para um operationId, sem cadeia if manual. |
| Dependência | Delphi XE7 ou posterior | O escaneamento e o dispatch code-first dependem de System.Rtti, indisponível antes do XE7. O spec-first não tem esse requisito. |
Um cliente genérico para qualquer endpoint descrito em OpenAPI, com autenticação Basic, bearer tokens, OAuth2 genérico e JWT genérico integrados.
| Recurso | API | Observações |
|---|---|---|
| Chamada base | HTTP_REQUEST | No TsgcOpenAPI_Client. Carrega um par TsgcOpenAPIRequest/TsgcOpenAPIResponse para qualquer endpoint. |
| URL base | SetBaseURL, GetBaseURL | O endpoint contra o qual todo caminho relativo de uma requisição é resolvido. |
| Autenticação genérica | Authentication (Basic, Token, OAuth2, JWT) | Autenticação Basic e bearer tokens, além de fluxos genéricos de OAuth2 e JWT. |
| Transporte | TLSOptions, ProxyOptions, EncodeBodyAsUTF8 | Configuração padrão de TLS e proxy compartilhada com o restante da pilha HTTP do sgc. |
| Progresso & logging | OnUpload, OnDownload, Log, LogFileName | Acompanhe corpos grandes de requisição/resposta e opcionalmente registre toda chamada em um arquivo. |
| Gancho de requisição | OnBeforeRequest | Inspecione ou altere uma requisição antes de ela ser enviada. |
| Ganchos de TLS | OnSSLVerifyPeer, OnSSLGetHandler, OnSSLAfterCreateHandler | Verificação de certificado e personalização de handler, compartilhados com o restante da pilha HTTP do sgc. |
Especificações públicas no wire, e o mesmo código-fonte em todo compilador compatível.
| Área | Detalhe |
|---|---|
| OpenAPI | OpenAPI 3.0 e 3.1, tanto para o roteamento spec-first do servidor quanto para os JSON Schemas contra os quais a validação de requisições verifica. |
| Autenticação do cliente | Autenticação HTTP Basic e bearer tokens, além de OAuth2 e JWT genéricos. |
| Métricas | Formato de exposição de texto Prometheus 0.0.4 em /metrics. |
| Plataformas | Windows Win32, Windows Win64, Linux64, macOS, iOS e Android para as sete classes. |
| Dependência | Nenhuma além do runtime sgcWebSockets Core embutido. Nenhum complemento adicional para qualquer uma das sete classes. |
| Compiladores | Delphi e C++ Builder 7 até 13. O OpenAPI code-first precisa do Delphi XE7 ou posterior. |
| Edições | A família do servidor REST também vem dentro do sgcWebSockets a partir da Professional, o servidor OpenAPI a partir da Enterprise, e o cliente OpenAPI a partir da Standard. |
| Licenciamento | Autônomo. O runtime sgcWebSockets Core vem embutido e o código-fonte completo está incluído. |