Todo lo que hace sgcREST, repartido entre el servidor REST y sus complementos, el motor del servidor OpenAPI y la familia del cliente OpenAPI. Cada capacidad funciona igual en Delphi y en C++ Builder, y todas las licencias incluyen el código fuente completo. Las subpáginas de componentes aún no están publicadas para este lanzamiento, cada entrada de abajo es autocontenida en esta página.
CORS, estadísticas, tenencia y usuarios
Spec-first y code-first
Consume cualquier API descrita con OpenAPI
Delphi 7 a 13, C++ Builder
sgcREST es autocontenido. Se entrega con el runtime sgcWebSockets Core incluido, así que no es un complemento, y funciona sobre la librería Indy estándar que se instala con RAD Studio.
OpenAPI code-first necesita Delphi XE7 o posterior. Generar una especificación a partir de una clase Delphi con atributos depende de la RTTI introducida en XE7. El servidor REST, sus complementos y el motor OpenAPI spec-first funcionan en Delphi 7 a 13.
Cuatro componentes en la página de paleta SGC REST, y tres clases solo de código del servidor y cliente OpenAPI, declaradas en las unidades sgcHTTP_REST_Server* y sgcHTTP_OpenAPI_*.
| Componente | Clase | ¿Paleta? | Descripción |
|---|---|---|---|
| Servidor REST | TsgcHTTPRESTServer | Sí | Servidor de API REST construido sobre TsgcHTTPServer, con gestión de CORS y complementos adjuntables de estadísticas/tenencia. |
| Estadísticas del servidor REST | TsgcHTTPServerStats | Sí | Contadores de peticiones, seguimiento de latencia, /metrics en formato Prometheus y /health en JSON. |
| Tenencia del servidor REST | TsgcHTTPServer_Tenancy | Sí | Resolución multi-tenant por host, ruta, cabecera o claim JWT. |
| Usuarios del servidor REST | TsgcHTTPServer_Users | Sí | Almacén local de cuentas: añade, valida, aplica hash, etiqueta roles y persiste usuarios. |
| Servidor OpenAPI, spec-first | TsgcOpenAPIServerHandler | No, solo código | Sirve una API desde un documento OpenAPI 3.0/3.1 cargado, con validación de peticiones. |
| Servidor OpenAPI, code-first | TsgcOpenAPICodeFirstScanner | No, solo código | Genera la especificación OpenAPI a partir de una clase Delphi con atributos RTTI. Necesita Delphi XE7+. |
| Cliente OpenAPI | TsgcOpenAPI_Client | No, solo código | Cliente de runtime genérico para cualquier endpoint descrito con OpenAPI. |
TsgcHTTPRESTServer es un descendiente de TsgcHTTPServer, así que parte de los mismos bindings y la misma gestión de TLS que comparte todo servidor HTTP de sgc, y añade encima los extras habituales de una API REST.
| Capacidad | API | Notas |
|---|---|---|
| CORS | CORSOptions (Enabled, AllowOrigins, AllowHeaders, AllowMethods) | Desactivado por defecto. Las peticiones preflight OPTIONS se responden automáticamente una vez activado. |
| Complemento de estadísticas | ServerStats: TsgcHTTPServerStats | Adjunta un componente de estadísticas y cada petición se cuenta y cronometra sin tocar los manejadores de ruta. |
| Complemento de tenencia | Tenancy: TsgcHTTPServer_Tenancy, Tenant | Adjunta un componente de tenencia para resolver el tenant de quien llama; Tenant lee el resultado para la petición actual. |
| Contadores de peticiones | TotalRequests, Status1xx a Status5xx | En TsgcHTTPServerStats. Se cuentan por clase de estado a medida que se envían las respuestas. |
| Latencia | LatencyMinMs, LatencyAvgMs, LatencyMaxMs | Se registra por petición en TsgcHTTPServerStats, se reinicia con Reset. |
| Endpoint de métricas | GetMetricsText, IsMetricsRequest | Formato de exposición de texto de Prometheus 0.0.4, servido en /metrics. |
| Endpoint de salud | GetHealthJSON, IsHealthRequest | Payload JSON de salud servido en /health, incluye UptimeSeconds y ActiveConnections. |
| Estadísticas por endpoint | GetEndpointStats, Endpoints | Un par ruta/contador por endpoint, para un informe o una consola de administración. |
| Resolución de tenant | Resolution, ResolveTenant | En TsgcHTTPServer_Tenancy. Resuelve por sufijo de host, segmento de ruta, cabecera o claim JWT. |
| Fuentes del tenant | HostSuffix, PathSegmentIndex, HeaderName, ClaimName, DefaultTenant | La fuente que se lee para el modo Resolution configurado, y el valor de respaldo cuando no produce nada. |
| Resolución personalizada | OnResolveTenant | Sobrescribe o amplía la lógica de resolución integrada. |
| Cuentas de usuario | AddUser, DeleteUser, FindUser, ValidateCredentials, SetPassword, EnableUser, UserExists | En TsgcHTTPServer_Users. Credenciales con sal y hash, nunca devueltas en texto plano. |
| Roles | AddRole, RemoveRole, UserHasRole, GetUserRoles | Etiquetas de rol de formato libre por cuenta, comprobadas desde un manejador de ruta. |
| Enumeración | Count, GetUserCount, GetUserByIndex, GetUsernames | Vistas de solo lectura para un informe o una consola de administración; el hash de contraseña y la sal nunca se incluyen. |
| Persistencia | LoadUsers, SaveUsers, SaveToFile, LoadFromFile, ExportUsers, ImportUsers | Storage.EncryptAtRest cifra el almacén; OnLoadUsers/OnSaveUsers permiten sustituirlo por un backend personalizado. |
| Eventos | OnStats, OnResolveTenant, OnValidateCredentials, OnFindUser, OnException | Un evento por complemento para los casos que la lógica integrada no cubre. |
Ambos enfoques alimentan la misma tabla de rutas y el mismo contexto de petición; solo cambia el origen del documento OpenAPI.
| Capacidad | API | Notas |
|---|---|---|
| Tabla de rutas | TsgcOpenAPIRouteTable (Add, Match) | Se construye a partir de la sección paths de una especificación; empareja un verbo y una ruta con un operationId. |
| Contexto de petición | TsgcOpenAPIServerContext (Request, Response, PathParams, QueryParams) | Una instancia por petición emparejada, liberada cuando termina la petición. |
| Parámetros tipados | PathParamAsString, PathParamAsInteger, QueryParamAsString, QueryParamAsInteger, QueryParamAsBoolean | Lee y convierte un valor de ruta o de consulta en una sola llamada. |
| Acceso al cuerpo | BodyAsString, BodyAsJSON, HeaderValue | Analiza el cuerpo de la petición una vez y guarda el resultado en caché. |
| Respuesta | RespondJSON, RespondError | Escribe un cuerpo JSON con un código de estado, o un payload de error estructurado. |
| Ciclo de vida de la petición | BeforeHandle, AfterHandle, HandleException | En TsgcOpenAPIServerHandler. Sobrescríbelos para añadir registro, comprobaciones de autenticación o mapeo de errores personalizado. |
| Validación | TsgcOpenAPIJSONValidator | Comprueba los cuerpos de petición y los parámetros de consulta y de ruta contra los JSON Schemas que declara la especificación. |
| Generación de la especificación | GenerateSpec, Title, Description, Version, BasePath | En TsgcOpenAPICodeFirstScanner. Produce un documento OpenAPI 3.0 a partir de la RTTI de una clase con atributos. |
| Atributos de contrato | sgcServiceContract, sgcRoute, sgcSummary, sgcDescription, sgcTag, sgcResponse | Atributos a nivel de clase y de método que rellenan la especificación generada. |
| Atributos de verbo | sgcHttpGet, sgcHttpPost, sgcHttpPut, sgcHttpDelete, sgcHttpPatch, sgcHttpHead, sgcHttpOptions | Declara el verbo HTTP que responde un método anotado. |
| Enlace de parámetros | sgcFromPath, sgcFromQuery, sgcFromHeader, sgcFromBody, sgcRequired | Declara de dónde se lee cada parámetro del método. |
| Despacho | TsgcOpenAPICodeFirstDispatcher (RegisterController, DispatchOperation, IsRegistered) | Invoca directamente el método anotado registrado para un operationId, sin cadena de if manual. |
| Dependencia | Delphi XE7 o posterior | El escaneo y el despacho code-first dependen de System.Rtti, no disponible antes de XE7. Spec-first no tiene ese requisito. |
Un cliente genérico para cualquier endpoint descrito con OpenAPI, con autenticación Basic, tokens bearer, OAuth2 genérico y JWT genérico integrados.
| Capacidad | API | Notas |
|---|---|---|
| Llamada base | HTTP_REQUEST | En TsgcOpenAPI_Client. Transporta un par TsgcOpenAPIRequest/TsgcOpenAPIResponse a cualquier endpoint. |
| URL base | SetBaseURL, GetBaseURL | El endpoint contra el que se resuelve cada ruta relativa de una petición. |
| Autenticación genérica | Authentication (Basic, Token, OAuth2, JWT) | Autenticación Basic y tokens bearer, además de flujos OAuth2 y JWT genéricos. |
| Transporte | TLSOptions, ProxyOptions, EncodeBodyAsUTF8 | Configuración estándar de TLS y proxy compartida con el resto de la pila HTTP de sgc. |
| Progreso y registro | OnUpload, OnDownload, Log, LogFileName | Sigue cuerpos de petición/respuesta grandes y, opcionalmente, registra cada llamada en un archivo. |
| Gancho de petición | OnBeforeRequest | Inspecciona o modifica una petición antes de enviarla. |
| Ganchos de TLS | OnSSLVerifyPeer, OnSSLGetHandler, OnSSLAfterCreateHandler | Verificación de certificados y personalización del handler, compartidas con el resto de la pila HTTP de sgc. |
Estándares públicos en el cable, y el mismo código fuente en todos los compiladores compatibles.
| Área | Detalle |
|---|---|
| OpenAPI | OpenAPI 3.0 y 3.1, tanto para el enrutado spec-first del servidor como para los JSON Schemas contra los que valida las peticiones. |
| Autenticación del cliente | Autenticación HTTP Basic y tokens bearer, además de OAuth2 y JWT genéricos. |
| Métricas | Formato de exposición de texto de Prometheus 0.0.4 en /metrics. |
| Plataformas | Windows Win32, Windows Win64, Linux64, macOS, iOS y Android para las siete clases. |
| Dependencia | Ninguna más allá del runtime sgcWebSockets Core incluido. Sin complemento adicional para ninguna de las siete clases. |
| Compiladores | Delphi y C++ Builder 7 a 13. OpenAPI code-first necesita Delphi XE7 o posterior. |
| Ediciones | La familia del servidor REST también se entrega dentro de sgcWebSockets desde Professional en adelante, el servidor OpenAPI desde Enterprise en adelante, y el cliente OpenAPI desde Standard en adelante. |
| Licencias | Independiente. El runtime sgcWebSockets Core viene incluido y se entrega el código fuente completo. |