I need to create both ends of an API between a Client and a REST Web Service. Please correct me when I use incorrect names etc as I have never ever done this before! This will be used both in-house and out so I need to make sure that the format etc is correct to best practices.
I am wondering what the major items that need to be included/expected by the Web Service? I think there are some items like version, login criteria and other? I have no idea how this should best be formatted, what order they should be in and other things that I am clueless about.
For the data request and data reply what is the proper format for this? I assume it will use JSON, but what are best practices?
Also:
What format should the verbs be? Upper case, Lower or CamelCase?
What special considerations for a URL Path?
How to best handle credentials for clients? What credentials should be included?
I have been watching the videos (a bit old but I bet the concepts are the same) that Paul made many years ago. Are there any books anyone can recommend?
When using a Web App as the Web Service, would it best to use the session object rather than the app.eventhandler? Or can the app.eventhandler manage multiple simultaneous request? If so, what is the limit??
I’m sure the answers will spawn more questions, but I would really appreciate any information on the subject that you can provide.
Hi Tim, I’m sure others will have better suggestions, but if I’d recommend writing an app to consume a Web Service and try pointing to a well-documented public API. This will give you a chance to study their API Docs and see how they handle naming conventions for the Get and Post functions, how they handle their security model, etc. You might use their examples as a template for your own architecture.
Will other clients use the REST web service, or just the client you’re writing?
Verbs are upper case by convention, but really they’re not case sensitive. Especially if you’re writing the web service in Xojo, which is case insensitive by default.
Verbs are practically meaningless any more. The URL path has more meaning, along with the JSON content of the request.
If you’re writing the Web Service in Xojo, then it will be a web app that only uses HandleURL. No sessions involved.
@William Thanks for the suggestion. can you direct me to a good one to use?
@Tim H - REST Service will be used by both my clients and others.
I was planning on using a web app made in Xojo. But how does it support >1 request at a time if not using sessions? Is the HandleURL object designed for multiple simultaneous connections?
Further, where/how did you guys learn about this stuff?
There was I think a pretty good Xojo blog post on the subject a while back, but the search function there isn’t great and I can’t find it anymore. @Javier_Menendez ?
Is this correct? I know you can have multiple Sessions at once, but I thought you can have only one HandleURL running at once, the rested are queued. Happy to be corrected.
For Client side, Xojo is OK.
For Server side… The Xojo one thread nature demands lots of queuing and postponed processing. It can’t handle well relatively small loads, like 25+ connections. And the last time I checked, it was presenting some accumulative leaks leading to a crash in a near future. That made users usually do some programmed “stop and reboot” before the dawn . Works for offices, for locals, don’t work for global audience being interrupted in the middle of their work day while you are sleeping.
If you go this way, do PoC tests before going deeper.
I like JSON-RPC for an API, it’s like a standard function call just with a little bit of serializing / deserializing JSON thrown in. There’s no need for the HTTP verb or url to change because the service + method you’re calling is contained within the JSON. A simple example request:
{
"id": "ABC123", // returned with the response
"service": "maths",
"method": "addition",
"params": [2, 2]
}
The params element can be as complex as needed for the method being called, for example if it were to create an invoice it might be a hierarchical object containing the header details and an array of invoice lines …
So on the server side you have a router script that uses the service and method members to marshal the request to the correct function and pass in the params
A few things I’d like to add… make sure your verbs and response codes make sense. There are a lot of APIs out there that don’t take advantage of them all and it makes it just a little harder to wrap your head around them. If you’re thinking of standard CRUD operations (Create, Read, Update, Delete):
Create > PUT
Read > GET
Update > POST
Delete > DELETE
In terms of http status codes, get a good list (Mozilla is my favorite) and use the correct ones. If an authentication fails, return 401 NOT AUTHENTICATED.
Lastly, if a record creation or update is going to take more than a few milliseconds, put the process in a thread or worker and return 201 CREATED with a url that the caller can query with GET or HEAD to find out if it worked. Status codes:
200 OK - when it’s done
100 CONTINUE - while the process is still running
4xx or 5xx for errors
I am working on an easy way to implement REST API functionalities.
I just subclass a certain API class.
I simply add the HTTP methods I need to this class.
The code in those methods will do what I want to do.
I add the results as a Field( FieldName ) = myValue
The rest of this little framework will make sure the data is being send to the client.
I am here as I just ended I2C and BLE efforts to connect satellite PICOs with a RaspPi5. The first attempt with I2C failed mainly due to connection distance with minor XOJO support capability which had to do with Controller - Multiple Peripheral using a token word protocol.
As a result I am now looking at using a REST implementation to communication using WiFi. I will need to have a compliment on the PICO written in C using VSC and on the RaspPi5 this needs to be integrated onto an app (ARM 64 not a WE app) that I have developed for the UI that mainly worked using I2C.
So in total ignorance of REST or JAVA I will ask is it possible to use WiFi to connect those devices so commands and data can be exchanged?
If yes and again in my total ignorance on this subject I need to quickly learn and implement. So if you have any suggestions with information I am all ears
REST API’s are generally just using the HTTP/S protocol. So you’re really just calling (or providing) a website. Adding REST into the mix just means the web content you’re pushing or receiving is typically in JSON format rather than HTML. In addition, REST usually requires adhering to some specific HTTP commands.
So using Wifi should be no different than a wired ethernet connection.
I think the challenge in your case, as you describe it, might be how your devices “discover” each other (public/secure Wifi access points?) and the authorization of HTTP/S port access.
The problem with WiFi is that the implementation will be in an RV. So consistent WiFi is not a given. Thats why I chose PICO WH and Pi5 as both have WiFi and BLE capabilities. I have been attempting to have PICOs listen on WiFi to commands from Pi5 but so far no good. When I say listen their WiFi is on but not associated to an AP or wireless router etc. I think it should be possible but no discovery yet. This would be simpler if I could count on WiFi in an RV. The full implementation will be a central Pi with Satellite PICOs controlling various aspects of an RV. Then the Pi can tell PICOs if there is a network to connect to when it exists and where to fallback to when it does not exist. I may need to see about setting Pi5 as Web Server while I run an ARM 64 APP (not WE) developed in XOJO. All new territory for me.
Again I am just on the beginning aspects of this. What attracted me was reading about CRUD capabilities with REST. I am on this route due to inability to do BLE with XOJO on Pi ARM 64 OS which was the direction I was heading until the cost of the license stopped that direction.
I will check the other links to what you provided and will have a go at this. I am still working on BLE in Pi5 using CLI and that may be a solution. The problem in that direction is I cannot get a smart device to see the BLE advertisement. This stuff is frustrating and fun all at the same time
