Currently I am working on a REST API and noticed, that for real REST it is essential to provide the possible HTTP operations of the resource within the HTTP response (e.g. in JSON-LD format).
After playing around with Swagger, I got to JSON-LD and Hydra, which in combination provide the foundation for real REST.
The problem with pure JSON-LD and Hydra is, that there is no real editor (the Playground does help for testing but not for editing).
Then I found Api Platform which sounds quite promising but I could not find any hint, that it supports real REST.
Does API Platform support HATEOAS in terms of providing the possible HTTP operations?
API Platform explicitly supports HATEOAS and they even encourage using Hydra. Their admin UI supports viewing the API through an OpenAPI lens or a Hydra lens.
Related
I'm thinking about trying to implementing a client for a particular json-rpc 2.0 service that could give a user some static typing guarantees. The API in question is very large, so actually writing a full-featured client by hand with all the necessary type information too big of a task for me to be bothered. However I've found via an undocumented http endpoint a large json based schema that seems to describe the entire json-rpc service fully. I'm certain I could write some sort of code generator using this specification. It is too big to paste here.
My question is, is there a standard specification for describing a json-rpc service? I've had a search around and I find a lot of dead links and the official spec[1] for json-rpc makes no mention of a standard schema definition for such a service. The schema I've found seems to be at least partially based off of the json-schema specification[2].
json-rpc
Json Schema
JSON Schema is great for defining payloads formats (you can even use it for REST APIs in OpenAPI) but indeed it won't help describe the "RPC" part, with the methods and entry points.
OpenRPC, created in early 2019, seems to be the most promising
The Ethereum Classic Labs Core (ECLC) team recently created the OpenRPC Specification, aiming to improve all blockchain dapp development. The specification emulates OpenAPI, the successful and widely adopted specification for REST APIs.
The OpenRPC Specification defines a standard, programming language-agnostic interface description for JSON-RPC 2.0 APIs.
Other approaches
Drupal JSON-RPC module provides a discovery endpoint and a Postman collection
The available RPC services along with documentation and usage details can be discovered by sending an HTTP GET request to /jsonrpc/methods.
You can use this Postman Collection with examples and tests.
There might also be interesting things to get from AsyncAPI, gRPC, GraphQL.
Dead
Also citing some other options I stumbled upon but which are dead:
JSON-WSP seems outdated, the Wikipedia page is pending deletion (talk page seems to say this was never actually a standard)
JSON-WSP (JavaScript Object Notation Web-Service Protocol) is a
web-service protocol that uses JSON for service description, requests
and responses. It is inspired from JSON-RPC, but the lack of a service
description specification with documentation in JSON-RPC sparked the
design of JSON-WSP.
JSON Schema Service Descriptor seems to have remained a draft
A JSON Schema service descriptor is simply a JSON Schema with the additional definition for methods.
A bit late but is this what you are looking for?
https://github.com/open-rpc/meta-schema/blob/master/schema.json
API Exploration
Although there are several questions that touch on the topic, none that I've been able to find address the core concept I'm trying to understand
If the root structure of an API is know, let's imaginatively say http://stackoverflow.com/api/service/ and we can successfully retrieve results from a know endpoint, let's say http://stackoverflow.com/api/service/answers/?id=39234, are there any methods, programmatic or otherwise, to identify other available endpoints?
Example
As an example, that's likely very source specific, googling the root url has revealed methods used in tags in pages from the source. I'm interested in similar broadly applicable techniques that may work.
I think it is not easy to answer your question in general, because there are a lot of different kinds of API's around in the world. For example:
Simple Object Access Protocol for which the API is often described via Web Services Description Language WSDL so you need to find the wsdl
For RESTful API's there are some more API description languages Overview of RESTful API Description Languages very famous is the OpenAPI specification
Also sometime you have XML documents that describe API's like in AVM's FritzBox router - which can be downloaded from the device.
Over the decades a lot more API descriptions have been developed like for CORBA
So it always depends on what kind of API's you are interested in and knowing the description languages for them and then to find the descriptions via search engines like google or Shodan etc.
I want to know the main difference between REST and API. Sometimes I see REST API in programming documents, then is REST or API same as REST API? I would like to know more about relation between REST, API and REST API.
REST is a type of API. Not all APIs are REST, but all REST services are APIs.
API is a very broad term. Generally it's how one piece of code talks to another. In web development API often refers to the way in which we retrieve information from an online service. The API documentation will give you a list of URLs, query parameters and other information on how to make a request from the API, and inform you what sort of response will be given for each query.
REST is a set of rules/standards/guidelines for how to build a web API. Since there are many ways to do so, having an agreed upon system of structuring an API saves time in making decisions when building one, and saves time in understanding how to use one.
Other popular API paradigms include SOAP and GraphQL.
Note that the above attempts to answer the question in regards to how the terms are commonly used in web development. Roman Vottner has offered a different answer below which offers good insights into the original definition of the term REST with more technical precision than I have provided here.
REST mostly just refers to using the HTTP protocol the way it was intended. Use the GET HTTP method on a URL to retrieve information, possibly in different formats based on HTTP Accept headers. Use the POST HTTP method to create new items on the server, PUT to edit existing items, DELETE to delete them. Make the API idempotent, i.e. repeating the same query with the same information should yield the same result. Structure your URLs in a hierarchical manner etc.
REST just is a guiding principle how to use URLs and the HTTP protocol to structure an API. It says nothing about return formats, which may just as well be JSON.
That is opposed to, for example, APIs that send binary or XML messages to a designated port, not using differences in HTTP methods or URLs at all.
There is no comparison in REST and API, REST is an API type.
API, in general, is a set of protocols deployed over an application software to communicate with other software components (Like browser interacting with servers) and provide an interface to services which the application software
offers to several live consumers.
And Rest is a form of principle which an API follows in which the server provides information whatever the client desires to interact with services.
REST basically is a style of web architecture that governs the behavior of clients and servers. While API is a more general set of protocols and is deployed over the software to help it interact with some other software.
REST is only geared towards web applications. And mostly deals with HTTP requests and responses. This makes it practically usable by any programming language and easy to test.
API is an acronym for Application Programming Interface and defines a set of structures (i.e. classes) one has to implement in order to interact with a service the API was exposed for. APIs usually expose operations that can be invoked including any required or supported arguments as well as the expected responses. Classical examples here are Corba IDL, SOAP or RMI in the Java ecosystem but also RPC-like usages of Web systems specified in documentation like Swagger or OpenAPI.
REST (REpresentational State Transfer) on the contrary was specified by Fielding in his doctoral thesis where he analyzed how the whole user interactions occurs on the Web. He realized that on the Web only a transport protocol, a naming scheme for stuff as well as a well defined exchanged format is needed to exchange messages or documents. These three parts therefore define the interface to interact with peers in such a ecosystem. The transport layer is covered by HTTP while the naming scheme is defined by URI/IRI. Contrary to traditional RPC protocols which usually only support one syntax, REST is actually independent from a particular syntax. To upkeep interoperability both client and server though need do negotiate about it, which HTTP itself supports through the Accept request and Content-Type response headers. As long as client and server support HTTP, URI/IRI and a set of negotiated representation formats, defined by backing hypermedia capable media-types, they will be able to interact with each other. In a more narrow sense REST therefore has no API other than HTTP, URI/IRI and the respective media types.
However, things are unfortunately not that easy. Most people unfortunately understand something very different in terms of REST or REST API. While URIs should not convey any semantics itself, after all they are just pointers to a resource, plenty of programmers attribute more importance to URIs than they should. Some clients i.e. will attempt to extract some knowledge off of URIs or consider URIs to return responses that represent a certain type. I.e. it may seem natural to consider an URI such as https://api.acme.org/users/1 to return a representation that describes a particular user of that particualar system. An external documentation may specify that a JSON structure is returned that follows a given template such as
{
"id": 1,
"firstName": "Roman",
"lastName": "Vottner",
"role": "Admin",
...
}
can be expected, however, such a thing is closer to RPC than it is to REST. Neither is the response self-descriptive, as required by REST, nor does it follow a representation format that follows a well defined media type that defines the syntax and each of the elements that may form a message. Clients therefore are usually tailor-made for exactly one particular system (or REST API if you will) and can't be used to interact with different systems out of the box without further manual integration/updates. External documentation such as OpenAPI or Swagger are used to describe the available endpoints, the payload-templates that a server will be able to process as well as the expected responses, depending on the input. These documentation therefore is the truth and thus defines the API a client can look up or even use to autogenerate stub classes to interact with the server-side, similar to SOAP.
I therefore don't agree with the answer given by dave. While for RPC systems or the common understood term of REST API his definition may be suitable, for actual REST architectures his explanation isn't fitting at all and thus, IMO at least, not correct either. REST isn't a collection of rules, standards and/or guidelines. It is a set of few constraints that just ensure that peers in such an architecture avoid coupling, support future evolution and become more robust to change.
API is basically a set of functions and procedures which allow one application to access the feature of other application
REST is a set of rules or guidelines to build a web API.
It is basically an architectural style for networked applications on the web which is limited to client-server based applications.
Read more at: https://www.freelancinggig.com/blog/2018/11/02/what-is-the-difference-between-api-and-rest-api/
Is it possible to consume a hateoas type of restful webservice via (a) javascript (framework - e.g. angularjs)? I imagine that the client needs to implement quite a lot of logic to reach the actual endpoint. Any feedback would be very much appreciated. Thanks!
At least part of the issue here is that your API needs to return a media type that supports structured linking (which the usual "REST" API defaults application/json and application/xml do not). To get this support, checkout the HAL or JSONAPI projects.
With a structured linking definition, it becomes much easier to consume - HAL has several libraries to work with it, including a javascript library:
https://github.com/mikekelly/backbone.hal
For an interesting client, checkout the HAL Talk demo.
Yes it is possible. Javascript is just another user-agent.
Yes there is work to do. No I am not aware of any frameworks to do this for you. I have written tooling for supporting hypermedia driving applications on the desktop and I don't consider it a significant amount of work to produce the infrastructure to support hypermedia based applications.
The challenge is less about the tooling and more about the fact that it is a very different approach to building applications. It takes some getting used to.
On a related note there is some ongoing work in the Browser/JS space that will make doing hypermedia driven applications on the client much easier. See NavigatingController.
Currently a JS user-agent can only manage javascript links. With NavigatingController it becomes possible to intercept HTML links also, making JS driven applications much more seamless in the browser.
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.