Skip to content

EndpointManager.md

Latest commit

 

History

History
286 lines (201 loc) · 8.69 KB

EndpointManager.md

File metadata and controls

286 lines (201 loc) · 8.69 KB

Endpoint Manager API

This API covers the resource endpoint lifecycle required for making resources publicly accessible. Using this API we can create, modify and remove one or multiple endpoints for a particular resource.

General notes and definitions

API Model

  • Model (application/json)

      [ EndpointInfo{
  		endpointPath | endpointPrefix : string
  		resourcePath : string
  	} ]

This API uses the EndpointInfo JSON model for creation of the endpoint and to communicate information about the endpoint. The model contains the endpointPath and the resourcePath parameters. Starting with version 1.4 of the endpoint manager, and 4.2 of active web elements server, the endpointPrefix can be used instead of the endpointPath.

Use of each parameter is described below:

  • endpointPath (string): This path uniquely identifies an endpoint which is publicly accessible from the active web elements server. If it is a hierarchical endpoint path (with a directory structure), it should be specified without a leading slash. For example, if under the directory test we have endpoint add, the path should be written test/add.
  • endpointPrefix (string): This path uniquely identifies the root for the set of endpoints that are publicly accessible from the active web elements server. An endpintPrefix functions as both an endpoint path and an endpoint directory. For example, if the endpoint prefix is test/add then the resource at resourcePath will be used to serve not just test/add but also test/add/one; however, it will not serve /test/addone. This is useful for e.g. deploying a URLDispatcher to WAS.
  • resourcePath (required, string): This path uniquely identifies a resource that should be accessible though the resource manager.

Exactly one of endpointPath and endpointPrefix must be specified. When multiple endpoints have been deployed such that there's an endpointPath or endpointPrefix for one that is inside a directory specified by another deployed endpointPrefix, the more specific (i.e. the innermost one) takes precedence. That is, for the following deployments:

    { "endpointPrefix": "foo", "resourcePath": "fooResource" }
    { "endpointPrefix": "foo/bar", "resourcePath": "barResource" }
    { "endpointPath": "foo/bar/baz", "resourcePath": "bazResource" }

then calls to:

  • foo/one will fire fooResource
  • foo/bar/one will fire barResource
  • foo/bar/baz will fire bazResource
  • foo/bar/baz/one will fire barResource (because bazResource is at a path, not a prefix)

Endpoints [/endpoints]

GET

Use this to retrieve the complete set of endpoints created. The API returns list of EndpointInfo objects in JSON format.

  • Request

      GET /endpoints

    Example:

      GET "http://applicationserver.wolfram.com/endpoints"

  • Response 200 (application/json):

    Example:

      {
  	"add" : {
  		endpointPath : "add"
  		resourcePath : "api/add.wl"
  	}
  	"country" : {
  		endpointPath : "country"
  		resourcePath : "api/country.wl"
  	}
  }

POST

Use this to create an endpoint for a specified resource file. The EndpointInfo object should be provided in the request body as JSON. The API returns the endpointPath of the newly created endpoint.

  • Request

      POST /endpoints

    Example:

      POST "http://applicationserver.wolfram.com/endpoints"

    Request body example (application/json):

      {
  	"endpointPath":"add"
  	"resourcePath":"api/add.wl"
  }

  • Response 201 Created (application/json)

      {
  	endpointPath : "add"
  }

  • If the resource referenced in resourcePath does not exist: Response 201 Created (application/json)

      {
  	endpointPath : "add",
  	warning: "no resource found at api/add.wl; users accessing this endpoint may receive a 404 Not Found error."
  }

  • If the endpointPath is null or empty: Response 400 Bad Request (application/json)

      {
  	"timestamp": "2019-07-16T18:32:17.516+0000",
  	"status": 400,
  	"error": "Bad Request",
  	"message": "endpointPath cannot be null or empty",
  	"path": "/endpoints"
  }

  • If the endpointPath already exists: Response 400 Bad Request (application/json)

      {
  	"timestamp": "2025-07-02T21:36:44.970730653Z",
  	"status": 400,
  	"error": "Bad Request",
  	"message": "There is already an endpoint at add",
  	"path": "/endpoints"
  }

In this case, use PUT instead as described below. This is a change from endpoint-manager version 1.2.5 and earlier.

  • If the resourcePath is null or empty: Response 400 Bad Request (application/json)

      {
  	"timestamp": "2019-07-16T18:32:17.516+0000",
  	"status": 400,
  	"error": "Bad Request",
  	"message": "resourcePath cannot be null or empty",
  	"path": "/endpoints"
  }

Note: Wolfram Application Server reserves a small number of endpointPath paths for internal usage. Attempting to assign a resource to one those paths will generate a 403 Forbidden error response.

  • Reserved endpointPath:

      .applicationserver/kernel/restart

  • If the endpointPath is a reserved path: Response 403 Forbidden (application/json)

      {
  	"timestamp": "2020-04-30T19:16:50.965+0000",
  	"status": 403,
  	"error": "Forbidden",
  	"message": "This endpointPath is reserved for internal purpose"
  }

Endpoints [/endpoints/{path}]

GET

Use this to get information about a specific endpoint. The API takes an endpointPath as a path variable and returns an EndpointInfo object in JSON format.

  • Parameter

    • endpointPath (String) : This path uniquely identify an endpoint.

  • Request

      GET /endpoints/{path}

    Example:

      GET "http://applicationserver.wolfram.com/endpoints/add"

  • Response 200 (application/json)

      {
  	"endpointPath": "add",
  	"resourcePath": "api/add.wl"
  }

  • If the endpointPath not exist: Response 404 Not Found (application/json)

      {
  	"timestamp": "2019-05-16T18:32:17.516+0000",
  	"status": 404,
  	"error": "Not Found",
  	"message": "Unknown endpoint",
  	"path": "/endpoints/add"
  }

PUT

Use this to modify an endpoint. The API takes an endpointPath (or, as of version 1.4, endpointPrefix) as a path variable and the EndpointInfo object should be provided in the request body as JSON. In this case, the endpointPath need not be redundantly specified in the request body, unless the intent is to change whether the path is a strict path or a prefix. If specified, the endpointPath or endpointPrefix must match the path element of the request. The API returns the endpointPath or endpointPrefix of the newly created endpoint.

Note that PUT cannot be used with version 1.2.5 of endpoint-manager or earlier.

  • Parameter

    • endpointPath (String) : This path uniquely identify an endpoint.

  • Request

      PUT /endpoints/{path}"

    Request body example (application/json):

      {
  	"endpointPath":"add"
  	"resourcePath":"api/add.wl"
  }

  • Response 202 Accepted. If the endpoint did not yet exist: Response 201 Created.

  • If the resource referenced in resourcePath does not exist: Response 202 Accepted (application/json)

      {
  	endpointPath : "add",
  	warning: "no resource found at api/add.wl; users accessing this endpoint may receive a 404 Not Found error."
  }

  • If the endpointPath in the request body does not match the path in the PUT request: Response 400 Bad Request (application/json). For example, PUT /endpoints/add with request body

      {
  	"endpointPath":"subtract"
  	"resourcePath":"api/add.wl"
  }

Response 400 Bad Request (application/json)

	{
		"timestamp": "2025-07-02T21:58:10.601525827Z",
		"status": 400,
		"error":"Bad Request",
		"message":"To modify subtract invoke PUT at /endpoints/subtract, not at /endpoints/add",
		"path":"/endpoints/add"
	}

However, PUT /endpoints/add with request body

	{
		"resourcePath":"api/add.wl"
	}

Response 202 Accepted.

  • If the resourcePath is null or empty: Response 400 Bad Request (application/json)

      {
  	"timestamp": "2019-07-16T18:32:17.516+0000",
  	"status": 400,
  	"error": "Bad Request",
  	"message": "resourcePath cannot be null or Empty",
  	"path": "/endpoints/add"
  }

DELETE

Use this to delete an existing endpoint. The API takes the path of the endpoint as a path variable and returns nothing.

  • Parameter

    • endpointPath (String) : This path uniquely identifies an endpoint.

  • Request

      DELETE /endpoints/{path}

    Example:

      DELETE "http://applicationserver.wolfram.com/endpoints/add"

  • Response 202 Accepted

Endpoint Health Check [/endpoints/.applicationserver/info]

GET

Use this to retrieve information about the endpoint manager. The API may be used to confirm that the endpoint manager is running.

  • Request

      GET /endpoints/.applicationserver/info

    Example:

      GET "http://applicationserver.wolfram.com/endpoints/.applicationserver/info"

  • Response 200 (application/json):

    Example:

      {
  	"name": "endpoint-manager",
  	"version": "1.0.0"
  }