Preparation to make API use proper HTTP verbs

pixeldesu commented

2022-09-28 08:21:19 +00:00

Owner

Currently, every endpoint in the Misskey API (scoped under /api) mainly accepts POST for requests.

We know that the API was envisioned to not be RESTy and "be something different", but there are enough endpoints where a regular GET would be enough. Technically, to appease those that complained, a setting allowGet exists for endpoints.

Still, the API could be so much better, especially for third-party developers.

I already talked about it on IRC and Fedi, but in the branch feature/api-v2-poc I played around with a concept to easily migrate endpoints to new verbs/methods, without having to rewrite the entire endpoint.

All endpoints include a meta constant with a bunch of options already, and I extended it the following way:

	/**
	 * API v2 options
	 */
	readonly v2?: {

		/**
		 * HTTP verb this endpoint supports
		 */
		readonly method: string;

		/**
		 * Path alias for v2 endpoint
		 * 
		 * @example (v0) /api/notes/create -> /api/v2/notes
		 */
		readonly alias?: string;
	};

If an endpoint has the meta.v2 object set, the API server router will register the same endpoint, but with the method specified in meta.v2.method, and a /v2/-prefix.

Ex.

POST /api/meta
GET /api/v2/meta

Additionally, if other route formatting makes sense, an alias can be specified.

POST /api/notes/delete
DELETE /api/v2/note

In the above branch, I also adjusted how parameters for endpoints are collected, and we now support the fairly common route parameters (e.g. /note/:id), which get properly plugged into the parameter definition for Foundkey.

POST /api/notes/delete (with noteId in the request body)
DELETE /api/v2/note/:noteId (noteId is a route param and not required in the body)

The main thing still missing (from my perspective at least) is adjustments to the API client to allow switching to the v2 endpoints easily.

This issue here is to collect further feedback or ideas that could be adjusted, without potentially breaking the actual (v1..v0?) endpoints.

Currently, every endpoint in the Misskey API (scoped under `/api`) mainly accepts `POST` for requests. We know that the API was envisioned to not be RESTy and "be something different", but there are enough endpoints where a regular `GET` would be enough. _Technically_, to appease those that complained, a setting `allowGet` exists for endpoints. Still, the API could be so much better, especially for third-party developers. I already talked about it on IRC and Fedi, but in the branch `feature/api-v2-poc` I played around with a concept to easily migrate endpoints to new verbs/methods, without having to rewrite the entire endpoint. All endpoints include a `meta` constant with a bunch of options already, and I extended it the following way: ``` /** * API v2 options */ readonly v2?: { /** * HTTP verb this endpoint supports */ readonly method: string; /** * Path alias for v2 endpoint * * @example (v0) /api/notes/create -> /api/v2/notes */ readonly alias?: string; }; ``` If an endpoint has the `meta.v2` object set, the API server router will register the same endpoint, but with the method specified in `meta.v2.method`, and a `/v2/`-prefix. Ex. ``` POST /api/meta GET /api/v2/meta ``` Additionally, if other route formatting makes sense, an `alias` can be specified. ``` POST /api/notes/delete DELETE /api/v2/note ``` In the above branch, I also adjusted how parameters for endpoints are collected, and we now support the fairly common route parameters (e.g. `/note/:id`), which get properly plugged into the parameter definition for Foundkey. ``` POST /api/notes/delete (with noteId in the request body) DELETE /api/v2/note/:noteId (noteId is a route param and not required in the body) ``` ---- The main thing still missing (from my perspective at least) is adjustments to the API client to allow switching to the v2 endpoints easily. ---- _This issue here is to collect further feedback or ideas that could be adjusted, without potentially breaking the actual (v1..v0?) endpoints._

pixeldesu added this to the (deleted) project 2022-09-28 08:21:19 +00:00

pixeldesu added reference feature/api-v2-poc

2022-09-28 12:53:46 +00:00

norm commented

2022-09-28 22:31:12 +00:00

Owner

Some questions I have about this API move:

Are we going to have new API endpoints that will only be available in v2?
If so, how would that get handled?

Some questions I have about this API move: 1. Are we going to have new API endpoints that will only be available in v2? 2. If so, how would that get handled?

Johann150 commented

2022-09-29 15:36:49 +00:00

Owner

I think with this system we would need to have an endpoint always be available in both APIs. I think that is fine, at least for now, especially since there is basically not much more work associated with having the endpoint in both versions. Pretty much the only added work is in maintaining the code that handles the new v2 attribute.

A concern that is "handled" by this is that we redesign the API while also retaining at least some compatibility with existing Misskey API consumers (e.g. mobile apps). If we decide at a later point that we no longer want to retain that compatibility we would have to think about redesiging this system, but for starters I think it is fine.

For consideration maybe the question: How much would we be tied to this system if we decide to redesign it at a later point? I don't think this is nearly as strict of a system as the old "design".

I think with this system we would need to have an endpoint always be available in both APIs. I think that is fine, at least for now, especially since there is basically not much more work associated with having the endpoint in both versions. Pretty much the only added work is in maintaining the code that handles the new v2 attribute. A concern that is "handled" by this is that we redesign the API while also retaining at least some compatibility with existing Misskey API consumers (e.g. mobile apps). If we decide at a later point that we no longer want to retain that compatibility we would have to think about redesiging this system, but for starters I think it is fine. For consideration maybe the question: How much would we be tied to this system if we decide to redesign it at a later point? I don't think this is nearly as strict of a system as the old "design".

pixeldesu commented

2022-09-30 11:17:02 +00:00

Author

Owner

well, for the most part v2 is a migration path for the old endpoints to mainly work the same, but be just that little bit better.

For new v2 endpoints we could probably support the same structure but load from a different set (like a endpoints/v2 subfolder) and just use the v2.method option right away as a single registration.

well, for the most part `v2` is a migration path for the old endpoints to mainly work the same, but be _just that little bit_ better. For new v2 endpoints we could probably support the same structure but load from a different set (like a `endpoints/v2` subfolder) and just use the `v2.method` option right away as a single registration.