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.
