Task Status

This page is part of the ongoing SWIM communities of interest discussions. The content is working material. It should not be treated as final as it is still subject to review, comment and change.

This page handles FAQ answers that are a work in progress.

Current FAQ

Updates

How do I describe a service that uses GraphQL?

GraphQL is allowed using HTTP as the transport layer (i.e. using WS-Light binding in SWIM-SERV-018 TI Profile and bindings).

GraphQL is an example of message-oriented service design (as opposed to operation-oriented or resource-oriented service design). For message-oriented services, the essential part is describing the data schema. GraphQL services do this in its own schema language “GraphQL Schema Language”.

-TBD-

How do I document the HTTP error codes in my service description?

My service relies on the standard HTTP error codes. Is there a need to document them in the service description?

The Examples/Notes section of requirement SWIM-SERV-220 Service behaviour explains that error messages and error handling in general can be included in a model view (as part of SWIM-SERV-330 Model view). They are modelled as part of the detailed service behaviour.

However, it is possible to add an entry in the service behaviour section of a service description. For example:

exception handling

The following HTTP status codes, with the meaning explained in the context of the service, are used by the service operations:

400 Bad Request: Indicated for malformed requests on the part of the client.

401 Unauthorized: Indicated for authentication errors (e.g. the authentication is not provided, the credentials used do not exists, the authentication mechanism used is not valid…).

403 Forbidden: Indicated for authorization errors (e.g. the authenticated credentials are not allowed to perform this operation on the resource).

404 Not Found: The requested resource cannot be found (e.g. the <subscription_id> does not exist).

405 Method Not Allowed: The HTTP method used is not supported by the resource.

500 Internal Server Error: Catch-all error for unexpected internal errors during the processing of the request.

Other error messages are documented in SWIM-SERV-280 Service messages.