V2 Endpoint Redesign (Suggestions)

[omosola]

V1 → V2 Endpoints

Base url: https://www.openml.org/api/v2/json

Proposal (@omosola)

	v1	v2	Notes
Data
	GET /data/{id}	GET /datasets/{id}
	DELETE /data/{id}	DELETE /datasets/{id}
	GET /data/list/{filters}	POST /datasets/search	Matches the Migration doc, and ElasticSearch and a few others do do it like this. Similar style used for all of the other resources (e.g. tasks, runs)
	GET /data/features/{id}	GET /datasets/{id}/features
	GET /data/qualities/{id}	GET /datasets/{id}/qualities
	GET /data/qualities/list	GET /dataset-qualities
	GET /data/unprocessed/{data_engine_id}/{order}	IN PROGRESS
	POST /data	POST /datasets
	POST /data/status/update	PATCH /datasets/{id}	Do we want to have a general PATCH to allow changes potentially to any of the fields? Or we can use distinct POSTs (or PATCH and reject some fields) to limit what can be updated in a dataset by the API
	POST /data/features	POST /datasets/{id}/features
	POST /data/qualities	POST /datasets/{id}/qualities
	POST /data/qualities/unprocessed/{data_engine_id}/{order}	IN PROGRESS
	POST /datasets/tag	POST /datasets/{id}/tags/	Could use PATCH if we don't worry about fully overwriting all tags, otherwise, probably better to do individual POSTs to add a tag, especially since adding individual tags is a common action.
	POST /datasets/untag	DELETE /datasets/{:id}/tags/:tag_string	Could use PATCH, but probably better to use DELETE or POST since this is a common one-at-a time action. You don't need to require access to the dataset's full tag array first before making this request.
Task
	GET /task/{id}	GET /tasks/{id}
	DELETE /task/{id}	DELETE /tasks/{id}
	GET /task/list/{filters}	POST /tasks/search
	POST /task	POST /tasks
	POST /task/tag	POST /tasks/{id}/tags
	POST /task/untag	DELETE /tasks/{:id}/tags/:tag_string
Flow
	GET /flow/{id}	GET /flows/{id}
	DELETE /flow/{id}	DELETE /flows/{id}
	GET /flow/list/{filters}	POST /flows/search
	GET /flow/exists/{name}/{version}	IN PROGRESS	Do we need this explicitly? You could also use the search functionality to see if you find a flow with this name and version and then you know if it exists or not? (Also, where would you find the flow's external version as a user?)
	POST /flow	POST /flows
	POST /flow/tag	POST /flows/{id}/tags
	POST /flow/untag	DELETE /flows/{:id}/tags/:tag_string
Run
	GET /run/{id}	GET /runs/{id}
	DELETE /run/{id}	DELETE /runs/{id}
	GET /run/reset/{id}	POST /runs/{id}/reset	Changing to POST as it has server side-effects.
	GET /run/list/{filters}	POST /runs/search
	GET /run/trace/{id}	GET /runs/{id}/traces
	POST /run/trace/{id}	POST /runs/{id}/traces
	POST /run	POST /runs
	POST /run/evaluate/	POST /runs/{id}/evaluations
	POST /run/tag/	POST /runs/{id}/tags
	POST /run/untag	DELETE /runs/{:id}/tags/:tag_string
Evaluation
	GET /evaluation/list/{filters}	POST /run-evaluations/search	Should this be merged with POST /runs/search endpoint. How are runs and evaluations different in the original API (the responses make them look similar)
	GET /evaluation/request/{evaluation_engine_id}/{order}	IN PROGRESS
Study
	GET /study/{id}	GET /studies/{id} // GET /task-collections/{id}
	DELETE /study/{id}	DELETE /studies/{id} // DELETE /task-collections/{id}
	GET /study/list/{filters}	POST /studies/search // POST /task-collections/search
	POST /study	POST /studies // POST /task-collections
	POST /study/{id}/attach	POST /studies/{id}/tasks	Adding a study from the v1 API call added a Task Collection. Also only id is possible to pass in and task and run IDs overlap, so it doesn't seem like it would add both types. Seems mostly like this endpoint is equivalent to POST /studies/{id}/tasks or something like this.
	POST /study/{id}/detach	DELETE /studies/{id}/tasks/{id}
Tasktype
	GET /tasktype/list	GET /task-types
	GET /taskype/{id}	GET /task-types/{id}
Setup
	GET /setup/{id}	GET /setups/{id}
	DELETE /setup/{id}	DELETE /setups/{id}
	GET /setup/list/{filters}	POST /setups/search
	POST /setup/tag	POST /setups/{id}/tags
	POST /setup/untag	DELETE /setups/{:id}/tags/:tag_string
Evaluation Measure
	GET /evaluationmeasure/list	GET /evaluation-measures
Estimationprocedure
	GET /estimationprocedure/list	GET /estimation-procedures
User (internal-only)
	GET /user/list	GET /users	Internal-only

General HTTP Responses for the above endpoints

• POST - 201, 400, 401, 403, (409 Conflict), 429, 500
• PATCH - 200 (or 204), 400, 401, 403, 429, 500
• GET - 200, 400, 404, 429, 500
• DELETE - 204, 400, 401, 403, 404, 429, 500
• Exceptions
  • POST /RESOURCE/:id/search - 200, 400, 429, 500