RESTful API - Endpoints (v1)

[FastFelix771]

Here, i wan't to define some of the first endpoints of the RESTful backend for API Version 1.0.0. (v1) We can discuss their structure, names etc. here and then reflect our changes into the code and the documentation / wiki.

Before i go ahead, i want to mention, that i use back.end as dummy domain for the purpose of the examples.

Endpoints would look like this example:

---

Name: Some Stuff URL: back.end/v1/some/stuff Method: DELETE Request: { json structure here } Response: { json structure here }

Some description.... ..... .....

---

So, lets define some endpoints... The endpoints we decide to use, will get listed here!

---

[jens1o]

Name: General ping URL: back.end/helloWorld Method: GET, Request: { apiVersion: USED_CLIENT_API_VERSION }, Response: { success: true, apiVersion: USED_SERVER_CLIENT_API_VERSION } with StatusCode 200 OK.

Response:

{
   success: false,
   apiVersion: USED_SERVER_CLIENT_API_VERSION,
   acceptableApiVersions: [ARRAY_OF_ACCEPTABLE_MINOR_API_VERSIONS (e.g. 3.1, 3.2, 3.3 when the server api version is 3.3)]
}

with StatusCode 424 Failed Dependency(?)

It simply checks whether the server is booted up and listens for clients... And also, we're checking whether they are compatible.

Thoughts?

[FastFelix771]

Since there are "success: true" statements anywhere, i assume this will be an unencrypted endpoint? Would make sense to me.

Sounds good so far, but i got one question: What client API? O.o Personally, i would suggest to use a scheme like back.end/v1/helloWorld and to use semantic versioning.

So, we would produce a version with a given set of functionalities we agreed on before. Then we implement this functionalities and provide security / stability patches etc. for it.

Then we bring together a bunch of new ideas, and wait until we got enough of them, then we raise the major version and go back to Step 1.

This way we can provide easy support for even older versions, by only keeping it safe and up-to-date. We also prevent to break any backwards-compatibility, because the calling Application has to choose one version to use - this would even allow for fall-back systems.

There are also things like global endpoints to speak of then, to get the API versions available for example. Something like u suggested here. We should put that topic into its own Issue, could u create one @jens1o ?

[jens1o]

Since there are "success: true" statements anywhere, i assume this will be an unencrypted endpoint? Would make sense to me.

Exactly.

Sounds good so far, but i got one question: What client API? O.o Personally, i would suggest to use a scheme like back.end/v1/helloWorld and to use semantic versioning.

This is a good idea, but it also has a downside...

What happens if a client supports multiple api versions and wants to know what the backend supports? It's supposed to brute force the available api version urls and see what happens? I would set a kind of main method, and once we know what api version is happening there, we can go specific.

We should put that topic into its own Issue, could u create one @jens1o ? We need to give it a name... what name?

[FastFelix771]

What happens if a client supports multiple api versions and wants to know what the backend supports? It's supposed to brute force the available api version urls and see what happens?

Thats what i mean with "global" endpoints... version independent endpoints. 2 or 3 of them, to get the available API versions, maybe some system infos and for a simple online-check?

[jens1o]

That's what I did there?

[FastFelix771]

That's what I did there?

Yepp. I was just confused what u mean with "Client API version" - but i think thats clear now.