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...

upload_2018-4-19_16-49-2.png


Video:
 

Mashiane

Expert
Licensed User
Longtime User
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!
 

OliverA

Expert
Licensed User
Longtime User
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

Expert
Licensed User
Longtime User
@OliverA I can now see the confusion with okHttpUtils2 (completely forgot about that one because I do not use it :oops:). 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:

B4X:
{
  "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.
 

OliverA

Expert
Licensed User
Longtime User
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.
 

keirS

Well-Known Member
Licensed User
Longtime User
@OliverA I can now see the confusion with okHttpUtils2 (completely forgot about that one because I do not use it :oops:). 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:

B4X:
{
  "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:

B4X:
{
    "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

Expert
Licensed User
Longtime User
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:

upload_2018-4-26_17-2-47.png
 

alwaysbusy

Expert
Licensed User
Longtime User
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

 
Last edited:

prajinpraveen

Active Member
Licensed User
Longtime User
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

Expert
Licensed User
Longtime User
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. :D

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? 😊
 
Top