Share My Creation OKAPIs: REST API Builder en Documenter

This is just a first look at OKAPIs (as in Okay APIs). It allows the creation, documentation and code generation for a B4J REST API. I have only been able to work a night or two on it yet, but this would be the 'public' view e.g. for third parties who want to use your REST API. More in the coming weeks...

Video:

 

[Mashiane]

What OKAPI means to a layman south african from kasi, http://www.okapi.co.za/... a knife, and one of the most dangerously used ones. My younger brother, at 19, lost his life to one from a thug. I like your version more. The stuff you expose us to here is marvelous AB! Keep it up man! Wow!

 

[alwaysbusy]

Pretty happy with my welcome screen...

 

[mindful]

@alwaysbusy is this something that you will release as a hosted/cloud app ?

Does this generate B4J Handler code ?

 

[alwaysbusy]

@alwaysbusy is this something that you will release as a hosted/cloud app ?

Does this generate B4J Handler code ?

This is indeed the plan

 

[Erel]

Looks great

 

[OliverA]

I'm pretty sure that without modification, B4X's okHttpUtils2 does not give you access to the HTTP status code. The only distinction that can be made if it was a 2xx code or not (Success = True, 2xx, False = non-2xx). Going by what is shown in post #1, how would one distinguish between 400 (Invalid input) and 401 (Unauthorized) without requiring a user use the source file of okHttpUtils2 and modify it? From helping out here on the Forum, I've noticed that a lot of REST API's seem to return 2xx codes even for invalid input and unauthorized. It is up to the programmer to read the JSON and see what the return result is.

I understand this creates the server side code for the API. I'm just looking at the usage of the API from the client side using B4X languages.

 

[alwaysbusy]

@OliverA I can now see the confusion with okHttpUtils2 (completely forgot about that one because I do not use it ). It is intended to be used with jServer (jetty) and there one has handlers where you can return the error codes yourself in the response after analysing the JSON. So like you say, the server side.

Maybe it would be a good idea that, next to the HTTP status code, I also return some JSON like:

{
  "status": 400,
  "message": "Invalid input"
}

Would this help? (as said, I don't know OkHttpUtils2).

I'm also thinking on third parties (who do not use B4X products), but still want to connect to a REST API created in B4X.

 

[Erel]

...and it is also very simple to add the status code to OkHttpUtils2.

 

[OliverA]

Would this help? (as said, I don't know OkHttpUtils2).

Yes, that would do it for the B4X client side and using a unmodified okHttpUtils2.
BTW, this is not unprecedented:
WooCommerce: https://woocommerce.github.io/woocommerce-rest-api-docs/#errors
Yahoo: https://developer.yahoo.com/gemini/guide/resources/error-codes/
Just providing some links to show that return JSON with the error information is not an odd convention.

...and it is also very simple to add the status code to OkHttpUtils2.

Yes, but I still think it is easier for most people to check the OkHttpUtils2 check box then to add the class source and modify it. Plus if anything ever changes with OkHttpUtils2, they have to remember to keep up with the changes. Maybe I should make a wish that the library expose the status code out of the box.

 

[Erel]

What I meant is that the OkHttpUtils2 can be updated and a new version of the library will be released.

 

[keirS]

@OliverA I can now see the confusion with okHttpUtils2 (completely forgot about that one because I do not use it ). It is intended to be used with jServer (jetty) and there one has handlers where you can return the error codes yourself in the response after analysing the JSON. So like you say, the server side.

Maybe it would be a good idea that, next to the HTTP status code, I also return some JSON like:

{
  "status": 400,
  "message": "Invalid input"
}

Would this help? (as said, I don't know OkHttpUtils2).

I'm also thinking on third parties (who do not use B4X products), but still want to connect to a REST API created in B4X.

The best REST API's do something along the lines of:

{
    "errorCode": 12345,
    "developerMessage": "Verbose technical description of what went wrong",
    "userMessage": "Simple message to display to user if required",
    "moreInfo ": "http://myrestapi.com/restapi/errors/12345"
}

Telling me it's invalid input is pretty meaningless. Be helpful and tell me which key value pair is invalid or if a key value pair is missing.

 

[alwaysbusy]

Telling me it's invalid input is pretty meaningless.

Of course, but this will be up to you who are building the REST API. You will be able to add codes + a meaningful message, like for example here codes 204 and 404 have a more meaningful message:

 

[alwaysbusy]

And because you can also add a json model (that you can also build yourself), give back such a structure like you describe. There is no reason you couldn't build a model 'error' like you showed.

 

[alwaysbusy]

Another step further in OKAPIS. This video shows you how easy it is to build a Json 'Model'. Using a simple scripting language (see at the msgbox at the end of the video for the syntax) the corresponding Json is auto generated for you. I'm using B4JS + B4JSJQuery (coming in ABM 4.30) to catch the keys in the ABMInput component and 'translate' it in real-time to the Json ABMCustomComponent, whithout ever going to the server.

The target is that the B4J generator would create a class from such a model. But I'm not there yet

anyhows...

Note: look at it on YouTube, in HD for a sharped version

 

[prajinpraveen]

Hello AB, do you have any update on this project. looks real fancy?

 

[alwaysbusy]

No, I've never been able to finish it Maybe one day, when I can find the time... Although, writing REST APIs these days is very simple in B4J and documenting/testing can easily be done with free tools like Postman/Swagger so I'm not even sure there is really a need for it.

 

[prajinpraveen]

Thanks AB, was just curious. I have written a huge API using ABM. works well. Thanks again for the wonderful framework.
I didn't document well and got interested when I saw your post.

 

[aeric]

No, I've never been able to finish it Maybe one day, when I can find the time... Although, writing REST APIs these days is very simple in B4J and documenting/testing can easily be done with free tools like Postman/Swagger so I'm not even sure there is really a need for it.

I wish to see this project continue. I think this framework would help more people to use B4X if they want to learn how to use B4X to build REST API server.

Thanks AB, was just curious. I have written a huge API using ABM. works well. Thanks again for the wonderful framework.
I didn't document well and got interested when I saw your post.

Sounds interesting. Mind to share more? maybe a youtube video? ?