Do you really know why you prefer REST over RPC?
apihandyman.io
apihandyman.io
Neither REST nor RPC is tied to HTTP at all. I think the title alone of section 6.3 of Fielding's dissertation, "REST Applied to HTTP", [1] should be enough to convince anybody that they're completely orthogonal concepts, much less the rest of the actual dissertation. The Wikipedia article for RPC [2] also provides numerous examples of RPC implementations that never even touch TCP, much less HTTP.
REST is literally just transferring some state via a representation. RPC is literally just calling a procedure remotely.
Also, yes, hatred of expecting different behaviors from different verbs is irrational. Because verbs indicate actions, and different verbs indicate different actions. It works well in written/spoken language, and it works well in REST and HTTP.
[1]https://www.ics.uci.edu/~fielding/pubs/dissertation/evaluati...
To be fair, you've kind of rephrased her point into a strawman that's simply opposed to the abstract concept of verbs.
Most of the time, people understand URLs as a one-to-one mapping - each URL has only one meaning, one website. It's not until you actually start writing code to create or consume an HTTP API that you need to learn the concept of the different verbs. In spoken language you don't become functionally fluent with the language and then some time later have a new concept of verbs introduced. So I can understand why the idea that "actually a URL (the part that everyone sees and knows) can have multiple meanings based on this hidden parameter" can feel wrong.
It's very very deliberately called an HTTP verb, for a reason.
It's not that I expect the average person, or even a new developer, should know that HTTP verbs exist or that URLs and URIs literally locate and identify resources in a uniform way. The part that bothers me is that when you deliberately write a blog about the subject that other developers may see and take as credible, you ought to put more effort into making sure your information is accurate before publishing.
I do appreciate the author's work here, I think the author was trying to help people clarify that REST/RPC don't need to be exclusive and that is helpful. All too often we encounter developers who want to sound smart and cool and state that it is "this tech" or "that tech" or NOTHING!
At a higher level of abstraction, representational state transfer should have nothing to do with HTTP semantics. It just so happens that we attribute REST with being related to HTTP semantics. But you could do REST with a non-HTTP protocol, if you wanted, why not?
Similarly, you can use a non-HTTP protocol in any other kind of framework for network based communication that you wanted...
And it just so happens that RPC is exposing functional, encapsulated units of code via network protocols and TCP/UDP sockets.
I remember trying to write my own network protocols for fun before over TCP and UDP sockets. Simple things like an echo service or a simple client/server application protocol. Doing that helps give one context for REST, RPC, SMTP, FTP, and more - semantics, concepts and frameworks over network connectivity.
The OSI model still matters. http://en.wikipedia.org/wiki/OSI_model
[Edit: I don't mind having a few RPC-style endpoints in a REST API. The world's not a perfect square and sometimes things just don't fit the resource-driven model well. But for example, for performing logins (something which I previously did via "POST /login"), I switched to doing a "POST /sessions", because that's what a login it is: adding a new session.]
Because HTTP's verbs weren't created with arbitrary operations in mind, but for specific, HTTP-related tasks.
REST GETs are fine for getters, and I generally like REST URLs because their prettier and don't have god-function smell like you get with SOAP.
But for commands, a POST with params to distinct URLs for each command works fine.
If you remember SOAP - the crazy approach to web services promoted before REST, you understand the difference REST made.
The same way AJAX is not about XML, REST for me is not about "representational state transfer", but just about using URLs to request operations from server.
The original REST idea of using HTTP error codes and forbidding application to create its own error classes and error reporting convention just doesn't work. HTTP errors only meaningful for HTTP - a transfer protocol, not for arbitrary application.
The point of using different HTTP verbs - chaching. Don't do
GET /deleteItem?itemId=456
So, I use HTTP URLs to communicate with server, and don't care to follow REST dogmas. It's more similar to what article calls "RPC" (actually RPC is more general term, in particular including SOAP).
The REST culture gives us some regularity. If we read github API, or google API or facebook API, we know what to expect - that they will use GET to retrieve an object, DELETE to delete an object and so on. It's good there is a convention helping to study new things.
Another good property of REST culture - it prevents people from building thick layers on top of HTTP. While not everything can fit into HTTP (at least error reporting, in my opinion; HTTP error codes are not enough), this culture helps to keep APIs simple.
To be fair, that's kind of like saying AJAX isn't about asynchronous requests.
Fielding doesn't agree with you. But that's your interpretation, and that's fine I guess. The point with Hypermedia APIs however is the "representational state transfer" via defined relationships between the resources.
Yes and no. Use DELETE for delete basically for that reason, but the statement that there are different verbs for caching is wrong. That's what a variety of Headers are there for. The fact that GET is in many cases cached simply is that a GET isn't there for state changes, so it doesn't matter whether it reaches the server (headers are there to tell whether it should).
That's for how things are meant to be, but I agree that it often isn't like that. Properties of HTTP were (ab)used for other things. I think that's a mixture of not understanding HTTP (in other words, not having read RFCs) and of course practical reasons.
We can see that a lot in the web in general. A lot of things get used in different, often completely wrong (as in standards breaking ways) and so things are not really coherent. That includes HTTP, HTML, CSS, ... and that's why new versions of these standards and up having a rather strong break. Caching is actually a great example if you look at HTTP/1 vs HTTP/2. But you may also be look at tags like <i> or <b> in HTML. They started out for styling, then they were discouraged and now they have a more semantic reasoning (see HTML 5's definition).
Doesn't mean that how it is used a lot is exactly bad. It actually just shows that the original ideas, the REST dogmas, etc. maybe don't fit and people use the best from RPC and REST. HTTP is used really universally, which also explains why there are things like WebSockets which barely fit with the original ideas and concepts of what HTTP is. On the other hand it worked extremely well, when you look at its popularity.
GET /api/resource
POST /api/resource/action
Where 'action' is something a bit more descriptive than 'PUT' or 'DELETE' or whatever. Kind of like an object-oriented api... I'm still always dealing with resources, but I have custom actions for specific use cases.
It is much easier to capture user intent with POST /api/customer/1/change-address-due-to-move { "address_1": "...", "address_2": "...", ... }
than with: PUT /api/customer/1 { "address_1": "...", "address_2": "...", ... }
Also, GET /api/resource/action is nice place for a payload describing the expected inputs to the action. Link it all together with hypermedia and you really have something ;)
Believe others are coming around to this line of thought: ThoughtWorks included "REST without PUT" onto their technology radar earlier this year.
POST /api/customer/1/address {"address": "..."}For example if I hand someone an API with a URI that accepts a PUT they know they can safely retry PUTs to that endpoint because the server state will always end up the same.
So PUT either creates or replaces a resource.
Definition of replaced:
> 1. take the place of.
Source: https://www.google.com.au/search?q=define%3A+replaced
It is pretty clear to me that the spec says PUT completely replaces the state of a resource. So not just a convention but what the spec says.
BUT lets take it further. Lets say you do allow partial updates with a PUT. Can you guarantee that your resource's state will always be internally consistent?
Say you have two clients, both doing partial PUTs and do the following:
Client 1: GET /foo
Client 2: GET /foo
Client 1: PUT /foo {'bar': 1}
Client 2: PUT /foo {'baz': 2}
So by allowing partial PUTs we're requiring the developer to consider all combinations a resource could be updated. They then need to communicate the valid combinations to any clients.
OR they can split the resource up finer grained resources, each one representing a valid PUT.
If you instead have the client tell the server what kind of change you want to make, and provide the parameters to the operation, the server can do everything that needs to be done and the client doesn't need to care.
POST /api/resource;action
As that doesn't pollute the idea that the path itself leads to a resource.
By (mostly) adhering to REST patterns you get so much stuff for free. Other developers can quickly get up to speed quickly. Client libraries are easier to write. Things like Ember Data work out of the box. I agree that every now and then doing a POST to /logout is easier than doing a DELETE /access_token/23, but a consistent API is far more worth it.
a simple example is a one-click payment + order action. you're creating multiple records in different tables - payment gateway transaction log, payment table, an order table, probably creating a customer record, sending email notification, logging a conversion, etc.
that sequence of actions does not adhere neatly to any HTTP verbs. it can be more clearly called "processorder" because it involves a lot more than creating an order record in a table. if you'd like, you can of course do POST /orders, but the nuance of what's happening is unnecessarily lost.
another example is a taking that order and marking it as "shipped". it is not a simple PATCH /orders/123 shipped=true. the front-end does not know all the fields that must be set in all the places on the backend. it is in fact a series of actions that take some data from the front, and some from the back and do a bunch of things that represent the setShipped() sequence.
HTTP verbs were designed for managing documents, for which they work well. They also happen to map well for direct db entries via CRUD. but trying to shoehorn them into all aspects of complex web apps is misguided. a true RPC is often what is necessary.
PATCH /orders/123 shipped=1
what does this do? does it simply set a field or does it trigger a shipOrder() sequence that also sets that field? what if you need the ability to do both (eg: admin interface & customer frontend)?
I understand that in this case you can instead do something like:
POST /shipments order=123
but not everything has a record backing it that would yield to this pattern. the response to a POST is supposed to be a Location header of the created record, so in fact you do need some form of URI and record for the created shipment.
HTTP REST's multi-item and hierarchical item management are also very hacked-in and necessarily too chatty. You cannot return multiple Locations in a header, for example, when multiple records are created. Strict adherence to the purity of HTTP verbs and limits quickly degenerates into custom hackery above and beyond the RFCs for anything mildly complex.
> the response to a POST is supposed to be a Location header of the created record
The HTTP spec says otherwise:
The action performed by the POST method might not result in a
resource that can be identified by a URI. In this case, either 200
(OK) or 204 (No Content) is the appropriate response status,
depending on whether or not the response includes an entity that
describes the result.
Again the HTTP spec allows you to manage this (though not in the header):
10.2.2 201 Created
The request has been fulfilled and resulted in a new resource being
created. The newly created resource can be referenced by the URI(s)
returned in the entity of the response, with the most specific URI
for the resource given by a Location header field. The response
SHOULD include an entity containing a list of resource
characteristics and location(s) from which the user or user agent can
choose the one most appropriate.
edit: was quoting HTTP 1.0 rather than 1.1
but here is a perfect example of multiple ways to do the same thing. and the custom additions to HTTP REST begin: multiple locations in the body of the response. the fact that sometimes the headers are sufficient, but at other times, you have to just create your own API to fill in the missing functionality using the response bodies.
no me gusta.
So return the URI of a list of records. Easy.
A user action doesn't have to correspond to a single API call. Your users single click could translate to multiple API calls.
Additionally, as others have already mentioned, a conceptual resource does not have to equal a database entry.
In an application (front and back end) there are probably three data models: whats in the database, the "resources" transferred over the API, and what the client has locally (in memory or disk or both) and these three don't necessarily have a 1:1 mapping. For example, in an application I'm working on, the client stores a transformed denormalised version of the resources that allows easy filtering/searching/sorting in the UI, the API resources are very regular semantic "things" and the database stores them in a way that is easy to index and perform access control checks on.
It would be silly to say that no API ever is not better represented as something else - for example, a bidirectional streaming API (running over, say, WebSockets?) is probably not a great fit for REST, but for request/response-based API's I do find that so far REST is really nice.
Some people say that actions or commands aren't nicely represented as resources, but personally I like the idea of POSTing to a command resource in order to tell the server to execute a command (and GET could be used to retrieve all outstanding commands, PUT to replace one, DELETE to cancel etc). Again, not requiring a 1:1 match between resource and database makes this possible.
However, even within the world of REST, people have different approaches, so at the end of the day, to each his own. Use what you feel is simplest and makes most sense.
E.g. sending money, transfer item, bulk modify A while update B, etc.
I like your approach because it avoids never ending debates.
In the end we made the API as REST(ful|ish) as possible and in places that we needed to be a little more flexible we tried to keep close to common practices. I think as long as your API is sane, easy to use, well documented (and tested), then users aren't going to care whether or not it is 100% RESTful.
Relevant: http://blogs.mulesoft.org/api-best-practices-response-handli...
In this case the client has sent an invalid request so the response should be 400 Bad Request or 422 Invalid Data, with details of the error in the response body.
The pet peeve issue I have with RPC/HTTP APIs is that people keep reinventing HTTP on top of it, only badly (at which point they may as well use RPC/TCP). That's why I like REST/HTTP, because I can "reuse things" when the problem model fits well within that tool (and it very often does). If REST/HTTP becomes a constraint instead of an asset, then maybe one should not use either REST or HTTP, and I'm fine with it because that was not the tool for the job.
This is a tool, not a religion.
Sometimes I have questions on which HTTP status code to use, but most of the time its pretty clear. And if you stick to the official codes most client side libraries will just work without any drama at all. As a bonus, all of the intermediate processes (proxies, firewalls, CDNs, etc.) will work as well without any finagling on your part. :)
I have designed both, and I find that the contortions you have to do to make your API RESTful is generally not worth it unless you're almost entirely CRUD and are mainly targeting the browser (and even then, you probably have a lot more nonCRUD actions than you think).
For everything else, RPC wins because you design it much like regular code.
Maybe the answer is just to use both, rather than trying to jam a square peg in a round hole.
Instead of defaulting to RPC, I like to try a few things:
1. Find some abstract resource that represents. POST to reboots to create a new reboot. In order to faithfully bring the resource into parity with the new state you've requested, the system reboots a machine. A GET to reboots should give you a list of previous reboots. Updating a reboot record might occasionally be necessary as well if an error occurred.
2. Model the state transition as simply another state. "Rebooting," for example, might be a state you can transfer that represents on -> off -> on.
I'll admit they don't roll off the brain as easily as calling the "reboot" procedure, but I also typically find that it brings a good amount of positives as well. For example, the ability to create reboots brings with it the ability to get a record of those reboots pretty trivially (if you're storing requests).
And for what it's worth, I've only found value in levels 1 and 2, not level 3.
Also, this talk by DHH helped me understand how to organize an API by creating more nouns with a restricted set of verbs, instead of proliferating verbs on a smaller set of nouns: http://www.bestechvideos.com/2007/08/12/railsconf-07-keynote...
If you look at frameworks like Backbone, you can basically create models/collections for a simple CRUD app just by adding some values to a declarative hash (URI, primary key, etc.). Because everything is so predictable, it's really easy to specify a default behavior.
Granted, you could certainly do something similar with an RPC API, but I still think it would likely be harder to generalize.
RPC leads to fragile protocols. Adding arguments to a procedure or adding properties to a result can often break clients and in practice you update systems lock step.
HTTP can gracefully handle different API version requests to the same resource. REST clients are encouraged to take only what they need from the representation.
Also, I strongly disagree with the Totaling points section. Seems too "nice" to both sides.
If the API you are writing has these features:
* you are the consumer as well as the author.
* no other developer is ever going to need to understand it.
* don't care about server/proxy/library support.
by all means don't bother with REST.
But if you are doing one/some/all of the above implementing a HTTP REST architecture is going to make your life and fellow developer's lives easier. That is what specifications are for, there to make things easier for everyone.
The thing I find most frustrating about these discussions is REST is such a simple architecture with a well thought out technical reasoning. Yet people happily ignore parts of it because of some unstated preference, and develop their own architecture which other developers then have to divine.
> The query component contains non-hierarchical data that, along with data in the path component (Section 3.3), serves to identify a resource . . .
source: https://tools.ietf.org/html/rfc3986#section-3.4
With a caveat, you will note the "non-hierarchical data" bit.
It means that this:
GET /user/1/groups
GET /user?id=1&groups
Why? The spec doesn't say of course but at a guess I'd say because there is already a hierarchical data format in URLs, the path. This assumption is build into every web framework & language I've ever used, with query strings being passed as unordered dictionaries.
As you suggest the convention is to only use query strings as search parameters and the like. Personally I think conventions are useful to follow, especially when they don't cost you anything like the one we're talking about.
POST /users/create
POST /users/1234/read
POST /users/1234/update
POST /users/1234/delete
POST /new_address_due_to_move.php?customer_id=1234,
But, in my experience, most requests consist of a "thing path" - host, resource; and then some "function" - get, update, other. POST is then the '=' - it's still a function under the hood, but because of it's commonality and interaction with language, the syntax is a little special.
In which case (and this is what I see in the APIs I most like) "the right thing to do" is to combine them, where you have pure REST when you're interacting with the object, but use RPC style when you're interacting with the object's actions.
Let's say I have some machinery exposed through an API, you might do:
GET host.com/machines/1 -> {"machine":"mixer","state":"off"} POST host.com/machines/1?state:on -> 200
because I'm interacting with its state. But if I need to interact with its functional actions:
POST host.com/machines/1/mix?substance1=h20&substance2=c02
it makes more sense to phrase it as an action. "I want you to start doing this". You could also phrase as a request for a state transition: POST host.com/machines/1?state:mixing&substance1=h20&substance2=c02
but (to me) that seems way weirder, generally.
I've got to go, but I think the answers change you go from physical resources to virtual ones, say, things that process information -
GET host.com/stock_analyzer/6/analyze?ticker=GOOG
where you might control state variables regarding the analysis algorithms using a REST-style.
Thoughts?
I think it's the opposite: REST deals with data, while RPC calls an operation that has side effects on some (potentially) unknown state.
Not arguing that one is better just offering my thoughts on the analogy.
> DELETE /users/1234
No! It would be
DELETE /sessions/12345
DELETE /users/1234/session
DELETE /users/1234/sessions/3
Unless you actually want to permanently stop the user from using the system, in which case
DELETE /users/1234
This to me is like arguing that object-oriented programming isn't really any better than procedural programming because I know how to write well-structured procedural programs. This is completely beside the point, which is that procedural programming as a style tends toward balls-of-mud programs (to simplify things), and object-oriented techniques were conceived of in order to address the characteristics of procedural programming that are the cause of this tendency.
I view RESTful API programming in a similar vein: RPC also has negative tendencies (such as the creation of fragile protocols), and REST addresses many, if not all of those. Most of the time for more people, RESTful techniques will lead to better service and API design than will RPC, just like for most of the people most of the time, object-oriented programming will lead to better programs than will procedural programming.
Another thing that struck me strange about the article is showing the RPC urls. When I was using Thrift, I never needed to think about URLs. I just needed to make sure that I was calling methods correctly.
I think RPCs are a good fit for organizations looking for a way for their service based architecture to communicate. I don't really like exposing RPCs as a public API or for web clients to interact with.
http://illuminatedcomputing.com/posts/2011/07/restless-doubt...
Basically, after form submit errors your location bar still says /widgets or /widgets/1 rather than /widgets/new or /widgets/1/edit, so bookmarking that page, or "like"ing it, or Ctrl-L + <Enter>ing are all broken. I'd much prefer a redirect back to the correct URL.
Also the distinction between "create" and "update" can break the back button, if the user creates something, then clicks back to edit their submission (because submitting a second time will create a second thing, not update their original thing). That's not Rails so much as REST in general.
if @foo.save
flash[:success] = "Saved"
redirect_to foos_path
else
redirect_to new_foo_path
end
1. Non-authenticated users can create users, and see a list of users with details that are public.
2. Authenticated users can view their own public and private details and have read/write access to most fields except is_staff.
3. Staff users have full permissions for users that belong to the country they are managing.
4. Superusers have access to everything.
Without the benefit of DSLs this would take hours to write all the if/else statements and unit test them. It would be a nightmare to do the same for all your endpoints. I assume you can write some abstraction functions to use for all your RPC endpoints but it'd be easier to reuse a library from past projects that had the same REST API design.
Example:
Row level:
permission_classes = [
Or(And(Or(IsOwner('id'), IsStaff), IsUpdateOnly),
And(AllowAny, IsReadOnly),
And(AllowAny, IsCreateOnly))]
is_public = And(IsActive, Is('is_public', True))
fields = {
'display_name': [],
('is_active', 'password', 'email'): [
Or(is_staff_or_owner, IsCreateOnly)
],
('full_name', 'slug',): [
Or(is_staff_or_owner, is_public, IsCreateOnly)
]
}A generic problem with REST APIs is they all handle collections, associating items with subcollections (including establishing and removing 1-to-many or many-to-many relationships between existing objects), query strings, authentication, and pagination very very differently. Not all APIs are discoverable either, many don't do structured error codes. Thus to talk to one, rather than just using client-library, more work has to be done, often repeated work in multiple languages. Lots of REST APIs aren't well discoverable and rely on special logic to form up URLs, and many have weird verb pollutions - modelling a long running job for instance, I've typically have done as posting a job descriptor to a job collection, because the standard verbs don't really apply.
All being said, I prefer a nice broweseable REST API, but despite the accursed "XML" in the name, XMLRPC was easy - there were bindings in multiple languages and it was easy to ask an API what methods were supported. Problems came in the undefined parts - like whether "None" could be passed, and so on.
I can design and build some very elegant REST APIs, but the clients DO have work to do, every time. A good example for me was trying to write to GitHub's API, and then being angry at the way pagination was overcomplicated and URLs were not discoverable. (It might have gotten better).
BTW, if you are doing Python and want a GREAT foundation in pagination, discoverability, and so on, I recommend Django REST framework. One catch is you may wish to extend some of the serializers to return URLs relative to other URLs.
I don't think RPC is evil so much - over HTTPS and backed by a good webserver, and done so that it's stateless (something a pre-forking webserver (esp with MaxRequestsPerChild in play in Apache) forces you into, not so much REST protocols all by itself), I think it's just not socially acceptable.
So statelessness good, having to write client-specific "flavors" of REST, well, it's just reality.
(In other news, I'm disappointed all my He-Man figures got sold in the 80s so I can't illustrate tech cartoons with them, well done)
IMO SOAP in its very early days was actually fairly pleasant, at least when compared to the existing alternatives (things like COM and CORBA, which, ew). XML-RPC was also nice, in a "keep it simple, stupid" kind of way.
Then of course SOAP crushed XML-RPC, the crew of the USS Enterprise got their hands on it, and the rest is (depressing) history.
But I never even imagined I'd hear somebody say SOAP was more pleasant than CORBA. Yes, working with is CORBA barely better than hitting your foot several times with a hammer, but relative to SOAP, it's a breeze.
Anyway, it's kind of depressing that even now the best RPC we have to show is REST. It's a problem that looks so simple from a distance, why can't somebody build something really great here?
But I really like the idea that the API can tell you about the API, and do kind of wish JSON REST APIs had similar patterns.
I think the main problem that XML runs into is that it's used a data interchange format and/or a data serialization, instead of a markup.
I think the bit you're missing from the XML APIs - that makes you re-implement things - is the lack of an API descriptive document (like the WSDL). If that was a thing, REST is at least as automatically ported as any XML API style. (Someone would still have to write the libraries that turn the document into objects/functions, but that happens with the XML stuff as well)
Emacs vs Vim
Destined to become one of the great debates of history.
We had a couple of problems with GET requests: all of our data ended up in the url (we have too much info that has to be passed, we stopped working on some browsers), and the data returned could be cached (which is a HUGE problem for us).
Now, POSTs can also be cached, but there are easy ways around it...you can do the same thing with a GET, but that means adding more information to the url.
Anyway, one we got to the point of forgoing all GET requests, we ended up just doing everything with a POST for simplicity.
For serving a filesystem over HTTP REST is great though. And all that caching stuff comes in handy.
From a practical API standpoint though, having two different encodings (GET in url with url parameter encoding, and POST with form encoded or JSON) is a pain and has caused a number of minor bugs and definitely extra work.
Using HTTP is basically a socket for JSON RPC style calls is I think the most straightforward route. In this you have one RPC per request, POST only, with a JSON request body and JSON response. If you use keep-alive it's similar to a socket but can go through some firewalls a bit easier, and has a built-in framing format and metadata thing. Also it works with existing log monitoring tools and frameworks.
Practically speaking, I don't know if I've ever had a querystring that was effectively too large, busting some browser-determined limit. If you did, you might as well use a POST instead of GET, because the request is unlikely to be cacheable (I'm assuming the reason its such a large string is that you're serializing a large form of values or using the querystring to persist state in some way [protip: this is a bad idea]), which is the main reason to prefer GET for the request. POST (according to HTTP semantics, may have side effects, but is not required to have side effects).
IMHO, the choice between HTTP verbs beyond GET vs everything else is mostly bikeshedding. As a convention its fine, but there aren't a lot of pragmatic technical reasons to go with one over the other (referring to PUT vs PATCH vs POST), despite the HTTP semantics.
POST /queries
{"query": "..."}
201 Created
Location: /queries/1001
GET /queries/1001
{"results": ...}
Don't let GETs edit data, if you use PUT make sure it's idempotent, DELETE looks dangerous, be sure not to waste that, and do whatever you want with POST.
def index
if request.put?
update_stuff
end
# get/put render same response content
end
GET /resources, POST /resources, GET /resources/id, PUT /resources/id, DELETE /resources/id
Five routes for one resource type. If you need more resources, you nest your URIs. Why would you need POST /deleteResource?idRes=id when you can just DELETE /resources/id?
Code reuse wins.
For example an API that allows you to get users might also have a job resource or action to perform RPC jobs on the server from a manage api path or similar.