What are some web apps that allow me to play with any REST APIs visually (by clicking) and also get some code generated (in any language) that captures what I have described visually?
Similar to Swagger or Google API Playground but allows me to talk to anything that speaks REST (assuming I have the proper auth credentials and I know what messages it understands).
Bonus points for something that can also "discover" what messages are understood, given a URL endpoint.
Microsoft has 2 that I know of
OData API explorer
The data market service explorer (requires signing in, and then you can access free data sets)
Considering that REST API's are going to follow their own conventions, terms, and have their own documentation (hopefully), this is an impossible problem. If you restrict your quest to visualizing API's that follow a "standard" form of self-documentation (see REST web service WSDL? for some hopeful scenarios) you might be able to accomplish this.
Or you can use something like http://www.programmableweb.com/ to discover tutorials, tools, examples, and mashups of various existing APIs.
You could mock an API at http://apiary.io/.
You could explore and existing one through tools (e.g. REST Console for Chrome)
What you can't have, is one-size-fits-all explorer for "every possible REST API." Some APIs follow conventions that others don't.
apigee and apihub (now part of mulesoft) are two that I frequently visit. Of the two, apigee is my preferred provider.
One of the reasons that you're not going to see a lot of websites like this is because of the same-origin policy. This means that you can't access a RESTful API located at api.google.com from a web app running at, say, www.restfiddle.com without sending all the API traffic through restfiddle.com's servers. Sites like JSFiddle can exist (and are used widely) because all the processing is done on the client side.
Browser plugins, however, are exempt from the same-origin policy. If you're using Chrome, try Postman. If your REST client doesn't need to be web-based, check out SoapUI. IntelliJ IDEA has a nice REST client as well.
Try Restlet Studio, it's the only visual API designer I've found, and seems pretty good, it imports and exports swagger & RAML.
http://studio.restlet.com/
Related
A consulting client will provide a REST API and I need to connect to it through a locally installed on-premises Matlab (not Matlab Production Server), download and crunch some data and then send the results back.
I don't have experience with REST API yet so please excuse if I am mixing terms.
Right now I am trying to understand which is the relevant documentation for me and there are two options I am looking at:
The methods listed here - https://nl.mathworks.com/help/matlab/internet-file-access.html?s_tid=CRUX_lftnav , all relate to a RESTful Web Service. I don't know yet if the client has a REST API that can be categorized as a web service (I am going to use it to access some client data) - would anybody know what the 'standard' use case for a REST API is and if it will likely be considered as a 'web service'? I guess the 'web' service part refers to the HTTP protocol and it does need to be a website?
Then there is a bunch of documentation related specifically for the Matlab Production Server, which seems to me to be a more general version of dealing with REST APIs - https://nl.mathworks.com/help/mps/restful-api-and-json.html
However, if I understand it well, the second option is exclusive to MPS (and this is not what we will be using to access the API - we will be using standard Matlab Standalone desktop version)
Appreciate any help and clarifications!
p.s. I have read REST api vs REST Webservice vs RESTFul web service and that has cleared some questions on the difference between REST Api and REST API web service but it is still somewhat unclear in my head.
Sounds like you want to use webread and webwrite.
The MPS stuff is where MATLAB acts as the REST API, i.e. MATLAB is the server...
With webread and webwrite you can read/write data to/from an external server that's nothing to do with MATLAB.
We are in the process of designing a front-end application with Angular which will call a jBASE server through RESTful APIs. APIs are created from jBASE component called jAgent.
Does jAgent support creating and verifying JWTs?
If not, what is the best way to handle authentication/authorization for the Angular application?
If we need to use JWTs, do we have to use a authentication middleware application (.NET Core or node.js) for that?
Great question! At the moment there is no handler within jAgent and our recommendation is to implement this, and advanced web server/API gateway technology by way of other applications like HAproxy or Kong.
An expansion of jAgent functionality to include things like this is something we're still considering but keep in mind, the power of jBASE lies in its native interactions with the host OS. Since there is no virtual OS layer it can be easier to plug and play off the shelf things to fill in for additional functionality, which gives you the flexibility to bring your own tooling.
In summary:
Not at the moment
Using an off the shelf package to act as your API gateway
Subject to the package you choose
That relegates jAgent to management of the API layer as it exists on the PICK/jBASE side while the off the shelf package manages your API security layer.
One other note for you--I noticed that you included a link to the old jBASE docs hosted on HelpJuice. It's worth mentioning that we've migrated those docs to docs.zumasys.com. You'll find the docs there to be more up to date, and also completely open sourced--part of the migration included their move to a GitHub repo, where we're happy to take community contributions.
For reference, the article you mentioned is available at https://docs.zumasys.com/jbase/connectivity/jagent/introduction-to-jagent-rest-services/.
Update:
One of our engineers has a program that will use openssl to generate the tokens for you, which you can find at https://github.com/patrickp/wjwt.
You will need openssl installed on the machine and in the path.
The WJWT.TEST program shows the usage. The important piece is the SECRET.KEY which is your internal KEY you use to sign the payloads.
When a user first authenticates you create the token with SIGN. Claims are any items/fields you wish to save/store. Do NOT put sensitive data in here as it is viewable by anybody. The concept is we sign this with our key, give it back to the client. On future calls the client sends the token and we pull it and call the VERIFY function which basically re-signs the payload and validates the signatures match. This validates the payload was not manipulated.
Activities such as expiration you would build into your code.
Long term we plan to take this library and refactor the code into our MVDB Toolkit library with more functionality. That library is something we provide to jBASE customers at no additional charge.
I am currently evaluating the framework "wolkenkit" [1] for using it in an application. Within this application I will have a user interface for tenant-based data management. Only authenticated users will have access to this application.
Additionally there should be a public REST API following common standards and being callable by public (tenant security done with submission of a tenant-based API Key within the request headers).
As far as I have found out, the wolkenkit REST API does not seem to fit these standards in forms of HTTP verbs.
But as wolkenkit at all appears to me as a really flexible and easy-to-use framework, I wonder how to basically implement such a public API.
May it be e.g. a valid approach to create an own web application which internally connects to the wolkenkit backend? What about the additional performance overhead then?
[1] https://www.wolkenkit.io/
In addition to the answer of mattwagl, I would like to point out a few things that you may be interested in.
First of all, since wolkenkit is based on CQRS, the application has a separate API for writing and reading. That means, that if you send a command (whose intent is to change state) this goes to the write API. If you subscribe for events or run a query, this goes to the read API.
This again means, that if you send a command, it's up to the write side to respond to it. As the write side is not meant to return application state, all it says is basically: "Thanks, I have received the command." To get the actual result you have to wait for the appropriate event, which means subscribing to the read API.
In the wolkenkit documentation there is a nice diagram which shows this in a clear way:
If you now add a separate REST API (which actually fulfills the requirements of REST), this means that you need to handle waiting for the result internally. In other words: Clients in wolkenkit are always meant to be asynchronous, REST is not. Hence it's your job to handle the asynchronous behavior of the wolkenkit APIs in your REST API. I think that this is the hardest part.
Once you have done this, you will have a synchronous REST API, and of course it will have some overhead. But I think that since its overhead is limited to passing through and translating network requests, it should be negligible.
Oh, and finally, there is another thing that you have to watch out for: Since REST as it was meant originally relies on the HTTP verbs to transport semantics, you need to map GET / POST / PUT / DELETE to the semantic commands of wolkenkit. As long as this can be done 1:1, everything's fine – problems start when there are multiple commands that (technically speaking) do an UPDATE.
PS: I'm also one of the developers of wolkenkit.
PPS: However you are going to solve this, I would be highly interested to hear from you! It would be very great if you could share your experiences with us, as you are most probably not the last one with this idea. If you want to contact us, the easiest way would be via Slack.
wolkenkit applications can be accessed using an HTTP- and a Websocket-API. These APIs are both provided by the tailwind module that wolkenkit uses under the hood. In the tailwind repo you can find a very simple documentation of the available HTTP routes.
You're right, the wolkenkit HTTP-API is not a classic REST-API. It's more RPC-style which in our experience is a good fit for applications. There are only 3 routes that your clients/tenants need to support: /v1/command (POST) is used for issuing commands. The commands you post should follow the command schema. /v1/events (POST) can be used for streaming events to clients. These events will follow the event schema. Finally you have /v1/read/:modelType/:modelName (POST) to read models. You can simply use HTTPie to test these routes.
Authentication of these APIs is currently done using OpenID-Connect. There's a very detailed article on how to setup authentication using Auth0. I'm not quite sure if this fits your use-case but you could basically use any Authentication Service that follows this standard or that is able to issue JWT tokens.
Finally you could also build your own JavaScript client-SDK that runs inside browsers by building a module that uses the wolkenkit-client-js under the hood. This SDK can just use the same API as any other client to connect to your application.
Hope this helps.
PS: Please note that I am one of the authors of wolkenkit.
For a SaaS startup I'm involved in, I am building both a RESTful web API and a couple of client apps on different platforms that consume it. I think I've got the API figured out, but now I'm turning to the clients. As I've been reading about REST, I see that a key part of REST is discovery, but there seems to be a lot of debate between two different interpretations of what discovery really means:
Developer discovery: The developer hard-codes copious amounts of API details into the client, such as resource URI's, query parameters, supported HTTP methods, and other details that they've discovered through browsing the docs and experimenting with the API's responses. This type of discovery IMHO necessitates cool linkage and the API versioning question, and leads to hard coupling of the client code to the API. Not much better than if using a well-documented collection of RPC's it seems.
Runtime discovery - The client app itself is able to figure out everything it needs with little or no out-of-band information (presumably, only a knowledge of the media types the API deals with.) Links can be hot. But to make the API very efficient, a lot of link templating for query parameters seems to be needed, which makes out-of-band info creep back in. There are possibly other difficulties I haven't thought of yet since I haven't gotten to that point in development. But I do like the idea of loose coupling.
Runtime discovery seems to be the holy grail of REST, but I'm seeing precious little discussion about how to implement such a client. Almost all REST sources I've found seem to assume Developer discovery. Anyone know of some Runtime discovery resources? Best practices? Examples or libraries with real code? I'm working in PHP (Zend Framework) for one client. Objective-C (iOS) for the other.
Is Runtime discovery a realistic goal, given the present set of tools and knowledge in the developer community? I can write my client to treat all of the URI's in an opaque manner, but how to do this most efficiently is a question, especially over low-bandwidth connections. Anyway, URI's are only part of the equation. What about link templating in the Runtime context? How about communicating what methods are supported, aside from making a lot of OPTIONS requests?
This is definitely a tough nut to crack. At Google, we've implemented our Discovery Service that all our new APIs are built against. The TL;DR version is we generate a JSON Schema-like spec that our clients can parse - many of them dynamically.
That results means easier SDK upgrades for the developer and easy/better maintenance for us.
By no means the perfect solution, but many of our devs seem to like.
See link for more details (and make sure to watch the vid.)
Fascinating. What you are describing is basically the HATEOAS principle. What is HATEOAS you ask? Read this: http://en.wikipedia.org/wiki/HATEOAS
In layman's terms, HATEOAS means link following. This approach decouples your client from specific URL's and gives you the flexibility to change your API without breaking anyone.
You did your home work and you got to the heart of it: runtime discovery is holy grail. Don't chase it.
UDDI tells a poignant story of runtime discovery: http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration
One of the requirements that should be satisfied before you can call an API 'RESTful' is that it should be possible to write a generic client application on top of that API. With the generic client, a user should be able to access all the API's functionality. A generic client is a client application that does not assume that any resource has a specific structure beyond the structure that is defined by the media type. For example, a web browser is a generic client that knows how to interpret HTML, including HTML forms etc.
Now, suppose we have a HTTP/JSON API for a web shop and we want to build a HTML/CSS/JavaScript client that gives our customers an excellent user experience. Would it be a realistic option to let that client be a generic client application? No. We want to provide a specific look-and-feel for every specific data element and every specific application state. We don't want to include all knowledge about these presentation-specifics in the API, on the contrary, the client should define the look and feel and the API should only carry the data. This implies that the client has hard-coded coupling of specific resource elements to specific layouts and user interactions.
Is this the end of HATEOAS and thus the end of REST? Yes and no.
Yes, because if we hard-code knowledge about the API into the client, we loose the benefit of HATEOAS: server-side changes may break the client.
No, for two reasons:
Being "RESTful" is a property of the API, not of the client. As long as it is possible, in theory, to build a generic client that offers all capabilities of the API, the API can be called RESTful. The fact that clients don't obey the rules, is not the API's fault. The fact that a generic client would have a lousy user experience is not an issue. Why is it important to know that it is possible to have a generic client, if we don't actually have that generic client? This brings me to the second reason:
A RESTful API offers clients the option to choose how generic they want to be, i.e. how resilient to server-side changes they want to be. Clients which need to provide a great user experience may still be resilient to URI changes, to changes in default values and more. Clients doing batch jobs without user interaction may be resilient to other kinds of changes.
If you are interested in practical examples, checkout my JAREST paper. The last section is about HATEOAS. You will see that with JAREST, even highly interactive and visually attractive clients can be quite resilient to server-side changes, though not 100%.
I think the important point about HATEOAS is not that it is some holy grail client-side, but that it isolates the client from URI changes - it is assumed you are using known (or developer discovered custom) Link Relations that will allow the system to know which link for an object is the editable form. The important point is to use a media type that is hypermedia aware (e.g. HTML, XHTML, etc).
You write:
To make the API very efficient, a lot of link templating for query parameters seems to be needed, which makes out-of-band info creep back in.
If that link template is supplied in the previous request, then there is no out-of-band information. For example a HTML search form uses link templating (/search?q=%#) to generate a URL (/search?q=hateoas), but nothing is known by the client (the web browser) other than how to use HTML forms and GET.
I have been reading about REST and SOAP, and understand why implementing REST can be beneficial over using a SOAP protocol. However, I still don't understand why there isn't the "WSDL" equivalent in the REST world. I have seen posts saying there is "no need" for the WSDL or that it would be redundant In the REST world, but I don't understand why. Isn't it always useful to programmatically bind to a definition and create proxy classes instead of manually coding? I don't mean to get into a philosophical debate, just looking for the reason there is no WSDL in REST, or why it is not needed. Thanks.
The Web Application Description Language (WADL) is basically the equivalent to WSDL for RESTful services but there's been an ongoing controversy whether something like this is needed at all.
Joe Gregorio has written a nice article about that topic which is worth a read.
WSDL describes service endpoints. REST clients should not be coupled to server endpoints (i.e. should not be aware of in URLs in advance). REST clients are coupled on the media-types that are transfered between the client and server.
It may make sense to auto generate classes on the client to wrap around the returned media-types. However, as soon as you start to create proxy classes around the service interactions you start to obscure the HTTP interactions and risk degenerating back towards a RPC model.
RSDL aims to turn rest like a hypermedia, in other words, it has more information than a service descriptor like WSDL or WADL. For example, it has the information about navigation, like hypertext and hyperlinks.
For example, given a current resource, you have a set os links to another resources related.
However, i didn't find Rest Clients that supports this format or Rest Server Solutions with a feature to auto generate it.
I think there is a long way for a conclusion about it. See the HTML long story and W3C vs Browsers lol.
For more details about Rest like Hypermedia look it: http://en.wikipedia.org/wiki/HATEOAS
Note : Roy Fielding has been criticizing these tendencies in Rest Apis without the hypermidia approach: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
My Conclusion : Now a Days, WADL is more common that Rest and Integration Frameworks like Camel CXF already supports WADL ( generate and consume ), because it is similar to WSDL, therefore most easy to understand in this migration process ( SOAP to REST ).
Let's see the next chapters ;)
Isn't it always useful to programmatically bind to a definition and
create proxy classes instead of manually coding?
Agree wholeheartedly, this is why I use Swagger.io
Swagger is a powerful open source framework backed by a large
ecosystem of tools that helps you design, build, document, and consume
your RESTful APIs.
So basically I use Swagger to describe my models, endpoints, etc, and then I use other tools like swagger-codegen to generate the proxy classes instead of manually coding it.
See also: RAML
There is an RSDL (restful service description language) which is equivalent to WSDL. The URL below describes its practice http://en.wikipedia.org/wiki/HATEOAS and http://en.wikipedia.org/wiki/RSDL.
The problem is that we have lots of tool to generate code from wsdl to java, or reverse.
But I didn't find any tool to generate code from RSDL.
WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate
However, REST uses the network protocol by using HTTP verbs and the URI to represent an objects state.
WSDLs tell you at this place, if you send this message, you'll perform this action and get this format back as a result.
In REST, if I wanted to create a new profile I would use the verb POST with a JSON body or http server variables describing my profile to the URL /profile
POST should return a server-side generated ID, using the status code 201 CREATED and the header Location: *new_profile_id* (for example 12345)
I can then perform updates changing the state of /profile/12345 using the HTTP verb POST, say to change my email addresss or phone number. Obviously changing the state of the remote object.
GET would return the current status of the /profile/12345
PUT is usually used for client-side generated ID
DELETE, obvious
HEAD, gets the status without returning the body.
With REST it should be self-documenting through a well designed API and thus easier to use.
This is a great article on REST. It really help me understand it too.
WSDL 2.0 specification has added support for REST web services too. Best of both worlds scenario. Problem is WSDL 2.0 is not widely supported by most tools out there yet. WSDL 2.0 is W3C recommended, WSDL1.1 is not W3C recommended but widely supported by tools and developers.
Ref:
http://www.ibm.com/developerworks/library/ws-restwsdl/
The Web Application Description Language (WADL) is an XML vocabulary used to describe RESTful web services.
As with WSDL, a generic client can load a WADL file and be immediately equipped to access the full functionality of the corresponding web service.
Since RESTful services have simpler interfaces, WADL is not nearly as necessary to these services as WSDL is to RPC-style SOAP services.