FOX4Work API Documentation: Main Endpoint

Endpoint Details

The /interface/Api.aspx endpoint serves as the central reception channel for all incoming API communications to FOX4Work. It manages connection, authentication, content format validation, and triggers internal business actions (USEREXIT).

Element Detail
Base URL [Your_Server_URL]/interface/Api.aspx
Technology ASP.NET Web Forms (VB.NET Code-behind)
Purpose Reception, authentication, and processing of incoming data (IDocs, business messages, etc.)

🛠 Request Lifecycle (Workflow)

The request processing follows a precise lifecycle:

  1. Pre-Initialization (Page_PreInit): Establishes the connection to the management engine (via Initialise).

  2. Loading (Page_Load):

    • Clears the HTTP response stream (Response.Clear()).

    • Determines content format (Content-Type).

    • Performs Authentication.

    • Calls the main processing function (Message_to_send) upon successful authentication.

  3. Processing (Message_to_send) : Validates the HTTP method and request body format, then executes internal business actions.

  4. Unloading (Page_Unload): Closes connections (Connection.CONNECTEUR_ARRET()).

Authentication Mechanisms

The endpoint supports four (4) distinct authentication mechanisms, checked in the following order. As soon as a set of credentials is found, the code attempts to authenticate the user.

1. Custom Access Token (Header)

  • Type: Token for specific use (likely for an application or client service).

  • Location: HTTP Header X-CS-Access-Token.

  • Format: A string representing the token.

  • Header Example:X-CS-Access-Token: your-secret-access-token

2. Query String Parameters

  • Type: Simple passing of credentials in the URL. Discouraged method for production due to security risks (visibility in logs and history).

  • Location: URL, after the ?.

  • Format: user and password

  • URL Example: /interface/Api.aspx?user=myuser&password=mypassword

3. Basic Authentication (Header)

  • Type: HTTP Standard. Credentials (username:password) are Base64 encoded.

  • Location: HTTP Header Authorization.

  • Format: Basic [Base64-encoded(username:password)]

  • Header Example: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

4. Bearer Token (Header)

  • Type: Typically used with OAuth 2.0.

  • Location: HTTP Header Authorization.

  • Format: Bearer [token]

  • Header Example: Authorization: Bearer my-secure-bearer-token

⚠️ Security Note: If none of the above methods provide credentials (Autorisation(0) is empty), the server returns a 401 Unauthorized code with the message BasicAuthRequired.

📥 Supported Content Formats

The endpoint will only proceed with request processing if the request’s Content-Type matches one of the authorized formats.

Supported Formats

MIME Type (Content-Type) Description
application/xml Standard XML
application/json Standard JSON
application/soap+xml SOAP Request
text/xml Alias for XML
text/plain Raw Text Data
text/csv CSV Data Format

Handling Unauthorized Content

  • If the Content-Type does not match any of the above formats, the server returns a 400 Bad Request code with the message UnauthorizedContext.

⚙️ Business Action Processing

Once authentication and content format are validated, the Message_to_send function takes over to trigger internal actions.

1. Authorized HTTP Methods

  • The code checks if the request method (REQUEST_METHOD) is authorized.

  • Allowed Methods: GET, POST, PUT, PATCH, DELETE.

2. Reading and Validating the Request Body (Payload)

The request body is read into the Message variable.

The Verifie_structure_post function performs a rudimentary structural validation based on the Content-Type:

Content-Type Validation Condition
Contains xml Body must contain < AND >.
Contains json Body must contain { AND }.
Others (text/plain, etc.) Validation is always True (No structural check).

⚠️ Warning: If the validation fails, the server returns a 405 Method Not Allowed code with the message Method Not Allowed.

3. Triggering Internal Processes (USEREXIT)

Two types of actions can be triggered using Query Strings:

A. Main Process (Interfaces)

  • Trigger: Always executed if the structure is valid.

  • Role: Launches the general interface processing (Device.LogEvent.Evenement_locfile.Interfaces).

B. Specific Sub-Action (Jobcall)

  • Parameter: jobcall (integer/enumeration).

  • Role: If the jobcall value is not equal to None (0), a secondary action is launched.

C. Action Filter (action)

  • Parameter: action (string).

  • Role: This parameter is passed to internal processes to filter which sub-actions to execute (allows only a subset of available API calls to run).

4. Logging

  • A complete trace of the received request is logged into the ERP_I table (likely an ERP error/event log). Data is truncated to 8000 characters.

↩️ Response Formats and Error Codes

The response is formatted based on the initial Content-Type sent in the request, using the Message_retour function.

Response Structure (Examples)

Content Type Response Format
xml / soap+xml / text/xml <response><code>[Status]</code><message>[Text]</message></response>
json {“response”: {“code”: “[Status]”,”message”: “[Text]”}}
text/plain / text/csv (defaults to text/xml for errors) <ApiError><code>[Status]</code><message>[Text]</message></ApiError>

Common Error Codes

HTTP Status Internal Message Description Origin
200 OK Ok or Business Message Successful processing. Message_to_send
400 Bad Request UnauthorizedContext Unsupported Content-Type. Page_Load
401 Unauthorized BasicAuthRequired No authentication information provided. Page_Load
401 Unauthorized InvalidCredentials Authentication failed (incorrect user/password). Page_Load
405 Method Not Allowed Method Not Allowed Structural validation of the request body failed. Message_to_send
500 Internal Server Error Invalid data Unhandled error (Exception) in the Try…Catch block. Page_Load

 

Tags