"Service" vs "API" is a pretty vague question. Often, the two terms are used interchangeably. "REST" vs "RPC" is a little easier to explain.
Usually with REST, a URL represents a specific resource such as a "user", an "account", etc.. Typically, you can create/retrieve/update/delete these resources by using the HTTP methods POST/GET/PUT/DELETE. To update the profile for user 1125 you might send the following:
POST /user/1125 HTTP/1.1
Host: wherever.com
Content-type: application/x-www-form-urlencoded
firstName=Davey&lastName=Jones&email=dj%40thebrineydeep.com
Anything you wanted to do with user 1125, you would send a request to the same URL. There are exceptions and variants of this idea, but that's the crux of it.
RPC services is more like just using a function library, which is bound to a specific URL. You might have a whole bunch of related functions all bound to the URL /services/json. Then if you wanted to change the profile for old Davey Jones, you would:
POST /services/json HTTP/1.1
Host: wherever.com
Content-type: application/json
{ "jsonrpc": "2.0",
"id": 1,
"method": "setProfile",
"params": [ 1125,
{ "firstName": "Davey",
"lastName": "Jones",
"email": "dj@thebrineydeep.com"
}
]
}
I personally like JSON-RPC better because:
- I don't have to try and fit all of my function calls into some kind of resource-to-url mapping that might not make sense
- We don't try to overload the HTTP response codes to indicate API errors. Every request returns a 200 response (unless there is a server error) and you know from the response body whether you got an error or not. JSON-RPC is particularly good at being explicit about error conditions.
Sometimes REST is better because:
- Sometimes the resource-to-URL mapping fits really well
- It is more intuitive for third parties to understand
- It offers a simpler model for just retrieving easily-identified information
I don't think either one is any easier to code.
Edit I changed the REST example to use the more common form-encoded data instead of JSON. But of course you can specify any data format you like with REST. It isn't carved in stone.
