api

API

Webside is based on a Smalltalk system implementing the following web API.

It's worth mentioning that this API is not "pure" REST at the moment of writing this documentation. However, extending it to be a REST-full API could bring some benefits to both Webside and other potential consumers interested in inspecting or controlling a Smalltalk system through HTTP. Of course, such a change would require upgrading Webside and this documentation accordingly.

The implementation of API calls, including helper services, is centralized in a class called API.

IDs

Resources are identified by a unique ID. The production of these IDs rely on the backend implementation and may vary from dialect to dialect. The only requirement is that they should be unique. For the sake of simplicity, they will be 1, 2, etc. along this documentation.

Sections

These are the different sections of the API.

Note: URL path does not include the base URI. The base URI targeting a particular Smalltalk system will be prompted at the moment of opening Webside.

General

These are general endpoints that apply to the system as a whole.

Method	Path	Description	Parameters	Payload
GET	/dialect	Retrieve the Smalltalk dialect		-
GET	/colors	Retrieve system colors		-
GET	/logo	Retrieve system logo		-
GET	/stats	Retrieve ststem stats		-
POST	/save	Save the image		-

Code

These are the endpoints used to retrieve system code: packages, classes and methods.

Method	Path	Description	Parameters	Payload
GET	/methods	Retrieve methods satisfying the condition specified in the query (or all the methods in the system if no condition is provided)	selector, category, accessing, using, assigning, sending, referencingClass, selectorMatching, ast, annotations, bytecodes, dissasembly, count	-
GET	/classes	Retrieve all subclasses of a given root class (if no root is provided, the uppermost class in the system is used). It is also possible get a tree-like structure as well as to limit the depth in the classes hierarchy	root, names, tree, depth. category	-
GET	/classes/{name}	Retrieve a given class	-	-
GET	/classes/{name}/superclasses	Retrieve superclasses a given class	-	-
GET	/classes/{name}/subclasses	Retrieve subclasses a given class	-	-
GET	/classes/{name}/variables	Retrieve instance and class variables of a given class	-	-
GET	/classes/{name}/instance-variables	Retrieve instance variables of a given class	-	-
GET	/classes/{name}/class-variables	Retrieve class variables of a given class	-	-
GET	/classes/{name}/categories	Retrieve categories of a given class	-	-
GET	/classes/{name}/used-categories	Retrieve categories used throughout the hierarchy of a given class	-	-
GET	/classes/{name}/selectors	Retrieve selectors of a given class	-	-
GET	/classes/{name}/methods	Retrieve methods of a given class	-	-
GET	/classes/{name}/methods/{selector}	Retrieve the method with the given selector in the given class	-	-
GET	/categories	Retrieve all categories in the system	-	-
GET	/usual-categories	Retrieve popular categories used throughout the system	-	-
GET	/packages	Retrieve all packages	names	-
GET	/packages/{name}	Retrieve a given package	-	-
GET	/packages/{name}/classes	Retrieve actual classes of a given package	extended, tree, names, category	-
GET	/packages/{name}/methods	Retrieve actual methods of a given package	-	-
GET	/search	Perform a search on the system	text, ignoreCase, position, type	-
GET	/autocompletions	Retrieve completion entries for a given code, position and context	-	-
GET	/classtemplate	Provide a class template	package	-
GET	/methodtemplate	Provide a method template	-	-
POST	/selectors	Find a selector in a piece of source code	-	-

Changes

Endpoints to apply changes and retrieve changes made to the system.

Method	Path	Description	Parameters	Payload
GET	/changes	Retrieve changes made to the system	author	-
POST	/changes	Apply a change to the system	-	change
GET	/classes/{name}/methods/{selector}/history	Retrieve historical changes on a given method	-	-

Basic CRUD operations

For the sake of simplicity, the API encourages the use of a single endpoint /changes for applying any change to the system.
However, as this may imply to count on some implementation of refactoring changes on the backend (and might not be the case), a basic set of CRUD operations on main meta-model objects should be provided. The data required for these operations should be the same as the one provided for the corresponding changes.

Method	Path	Description	Parameters	Payload
POST	/packages	Add a new package	-	package
DELETE	/packages/{name}	Remove a given package.	-	-
POST	/classes	Define a new class or change the definition of an existing one.	-	class
DELETE	/classes/{name}	Remove a given class.	-	-
POST	/classes/{name}/methods	Compile a method in a given class.	-	method
DELETE	/classes/{name}/methods/{selector}	Remove a given method.	-	-

Changesets

Endpoints to convert changesets (chunks file) to/from changes.

Method	Path	Description	Parameters	Payload
POST	/changesets/download	Convert a set of changes (JSON) into a chunk formatted-file	-	[change]
POST	/changesets/upload	Convert a chunk-formatted file into a set of changes (JSON)	-	string

Evaluations

Endpoints to evaluate expressions and manage active evaluations.

Method	Path	Description	Parameters	Payload
POST	/evaluations	Evaluate an expression	-	evaluation
GET	/evaluations	Retrieve active evaluations	-	-
GET	/evaluations/id	Retrieve the evaluation with a given ID	-	-
DELETE	/evaluations/id	Cancel the evaluation with a given ID	-	-
POST	/evaluations/id/pause	Pause the evaluation with a given ID	-	-
POST	/evaluations/id/resume	Resume the evaluation with a given ID	-	-

Objects

Endpoints to retrieve the objects in the system, either globally accessible or as the result of evaluating an expressions.

Method	Path	Description	Parameters	Payload
GET	/objects	Retrieve pinned objects	-	-
GET	/objects/{id}	Retrieve the pinned object with a given ID	-	-
DELETE	/objects/{id}	Unpin the object with a given ID	-	-
GET	/objects/{id}/*	Retrieve the object reached thru the given URI	-	-
POST	/objects	Pin the object reached thru the given URI	-	object URI
DELETE	/objects	Unpin all pinned objects	-	-

Workspaces

Endpoints to manage workspaces.

Method	Path	Description	Parameters	Payload
GET	/workspaces	Retrieve active workspaces	-	-
POST	/workspaces	Create a new workspace	-	-
GET	/workspaces/{id}	Retrieve the workspace with a given ID	-	-
PUT	/workspaces/{id}	Update the workspace with a given ID	-	-
DELETE	/workspaces/{id}	Delete the workspece with a given ID	-	-
GET	/workspaces/{id}/bindings	Retrieve bindings of the workspece with a given ID	-	-

Debuggers

Endpoints to manage debuggers and interact with them.

Method	Path	Description	Parameters	Payload
GET	/debuggers	Retrieve open debuggers	-	-
POST	/debuggers	Create a debugger upon an given process (evaluation)	-	evaluation
GET	/debuggers/{id}/frames	Retrieve frames of the debugger with a given ID	-	-
GET	/debuggers/{id}/frames/{index}	Retrieve the i-th frame withing the debugger with a given ID	-	-
GET	/debuggers/{id}/frames/{index}/bindings	Retrieve the bindings of the i-th frame withing the debugger with a given ID	-	-
POST	/debuggers/{id}/stepover	Step over the current sentence in the debugger with a given ID	-	-
POST	/debuggers/{id}/stepthrough	Step through the current sentence in the debugger with a given ID	-	-
POST	/debuggers/{id}/stepinto	Step into the current sentence in the debugger with a given ID	-	-
POST	/debuggers/{id}/restart	Restart the debugger with a given ID	-	-
POST	/debuggers/{id}/resume	Resume the process of the debugger with a given ID	-	-
POST	/debuggers/{id}/terminate	Terminate process being debugged and closesthe debugger with a given ID	-	-
DELETE	/debuggers/{id}	Closes the debugger with a given ID (terminating the process being debugged)	-	-

Testing

Endpoints to run tests and retrieve their results.

Method	Path	Description	Parameters	Payload
POST	/test-runs	Create and run of a test suite	-	suite
GET	/test-runs/{id}	Retrieve the status of a given test suite run	-	-
GET	/test-runs/{id}/results	Retrieve the restuls of a given test suite run	-	-
POST	/test-runs/{id}/run	Re-run a given test suite	-	-
POST	/test-runs/{id}/debug	Debug a test withing a test suite run	-	-
POST	/test-runs/{id}/stop	Stop an active test suite run	-	-
DELETE	/test-runs/{id}	Delete a test suite run	-	-

Profiling

Endpoints to manage profilers and access their results.

Method	Path	Description	Parameters	Payload
POST	/profilers	Create a new profiler on a given expression	-	expression
GET	/profilers	Retrieve active profilers	-	-
GET	/profilers/{id}	Retrieve the profiler with a given ID	-	-
GET	/profilers/{id}/tree	Retrieve a tree-like results of a given profiler	-	-
GET	/profilers/{id}/ranking	Retrieve ranked results of a given profiler	-	-
DELETE	/profilers/{id}	Delete a given profiler	-	-

Extensions

Retrieve IDE extensions defined by the backend.

Method	Path	Description	Parameters	Payload
GET	/extensions	Retrieve list of change defintions	-	-