I want to create a set of REST API endpoints to expose various data sources. I want my endpoints to comply with the Richardson Maturity Model, specifically with support for HATEOAS.
I've looked over both JSON-LD and JSON:API and they both seem to be a good fit in that they can both equally support REST and HATEOAS, however JSON:API has a bunch of other features which are more 'gRPC-like'.
Are there any clear advantages to using JSON-LD Vs. JSON:API for REST endpoints? What are the feature differences which are applicable to REST?
Related
Just to clarify what I mean by RESTful, it should satisfy the following constraints, taken from here:
Uniform Interface
Stateless
Cacheable
Client-Server
Layered System
Code on Demand
From my research, I believe that they aren't RESTful, primarily because :
They do not use HTTP verbs.
They do not use HTTP Response Codes.
They does not follow principles of REST connectedness which is based on HATEOAS.
Refer this resource for more information about data above conclusions are based on.
Some resources like these seem to suggest these frameworks can be used/implemented as RESTful.
Please refer to resources you're basing your answer on. This question is intended to clear the misconception about the topic strongly citing official resources.
Are RPC frameworks such as Apache Thrift or GRPC or any other RPC framework RESTful?
Taken in isolation: no.
The definitive reference on REST is Architectural Styles and
the Design of Network-based Software Architectures. Roy Fielding describes the architectural constraints that were developed while working on the web standards (RFC 1945, RFC 2068, RFC 2616, later RFC 7230).
REST is intended for long-lived network-based applications that span multiple organizations (Fielding, 2008)
"The World Wide Web" would be an example of an application built using the REST architectural style.
HTTP methods and status-codes are not themselves a REST constraint. In a REST architecture, the client and server share semantics by exchanging messages, but those aren't required to be HTTP messages. You could replace HTTP with another protocol that conforms to the architectural style, and still have a REST architecture.
Some resources like these seem to suggest these frameworks can be used/implemented as RESTful.
People who understand REST to mean HTTP+JSON are going to reach conclusions that are inconsistent with the web architecture and Fielding's thesis.
In short - HTML does a lot of the heavy lifting in making the web architectural style successful. JSON, in contrast, does not include the semantics of a "link" or a "form" that can be used to communicate to the client which transitions are possible. You need some other semantics on top of JSON to allow the server to communicate to the client which application transitions are possible; either Web Linking or a hypermedia aware dialect of JSON.
As far as can tell, you could use Thrift to create an application that satisfies the REST architectural constraints. But my guess is that it wouldn't be a particularly satisfying experience: Thrift was developed because Facebook needed a system with properties that the Web architecture didn't satisfy.
REST is great for the web. Howver, the stack composed of REST, HTTP and JSON is not optimal for high performances required for internal data transfer. Indeed, the serialization and deserialization of these protocols and formats can be prejudicial for overall speed. -- Leo Schoukroun
URI, HTTP, HTML are easily repurposed, but that flexibility comes with costs. In settings where that flexibility doesn't provide value (for instance, because you are a single organization that controls deployment of the client and the server), then more efficient formats and protocols become more interesting.
It's similar to the trade off that we've made between HTML and JSON -- JSON isn't a useful hypermedia representation; but it's perfectly satisfactory for consumption by the code on demand that has been loaded by our hypermedia representation.
Horses for courses.
REST is by definition not RPC, because the most significant distinction of REST is that it is resource oriented, which RPC is (typically) not.
Furthermore, one should refrain from trying to solve problems that are crying for RPC by inventing some "RPC over REST" solution - Programmers SE is full of these kind of questions.
In fact, such an approach would be upside down: One can implement a REST-based system by means of RPC, but the whole idea why one would want to use REST is on a completely different abstraction plane.
So I'd say the question is (sort of) a category mistake.
Is there any difference between REST Assured and RESTful web services?
What is REST?
REST stands for Representational State Transfer, which is an architectural style for distributed hypermedia systems, frequently used to build web services that aim to be lightweight, maintainable and scalable.
The REST architecture was defined by Roy Thomas Fielding in his dissertation and should follow this set of constraints:
Client-server
Stateless
Cache
Uniform interface
Layered system
Code-on-demand
The fundamental concept in a REST architecture is the resource and resources can have different representations. For more details, this answer can be helpful.
It's also worth mentioning that the REST architectural style is protocol independent but it's frequently designed over the HTTP protocol because it is largely adopted and well known.
What is RESTful?
A service based on the REST architecture, following the constraints mentioned above, is called RESTful.
What is REST Assured?
REST Assured is a tool that aims to bring simplicity for testing and validating the response of REST services in Java.
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/
We use Swagger-based REST API specification for different projects. So each project has its own Swagger UI with a description of endpoints. All these UIs are deployed on different servers, under different domain names, which is not cool at all from the organisation perspective.
Are there any nice options to store multiple Swagger specifications in a single place? It could be any service for a REST API descriptions management, which consumes the Swagger Specification.
I found some nice options for a REST API specifications management:
Apiary (apiary.io)
Restlet (restlet.com)
SwaggerHub (swaggerhub.com)
All the three services support the OpenAPI Specification, which is based on the Swagger 2.0 spec.
Apiary has a good collaboration management and supports a REST API validation.
However, it is pretty expensive. A suitable plan costs 99$ per month: apiary.io/pricing
Restlet also has a possibility for a collaborative work and it supports a functional testing.
Comparing to Apiary, Restlet has a better choice of pricing options: restlet.com/pricing
SwaggerHub is the most optimal choice in my case. It is designed especially for multiple Swagger specifications management. The service has a support of all the code generators developed for Swagger. Nevertheless, it does not provide REST API testing/validations tools unlike Apiary and Restlet.
The biggest advantage of SwaggerHub is pricing. A ratio of specifications number per $ is the best with a maximum number of 25 collaborators on each API: swaggerhub.com/prices
What is basic difference between restful and restless, i've been reading a few articles people seem to use them interchangeably.
REST stands for REpresentational State Transfer and goes a little something like this:
We have a bunch of uniquely addressable 'entities' that we want made available via a web application. Those entities each have some identifier and can be accessed in various formats. REST defines a bunch of stuff about what GET, POST, etc mean for these purposes.
the basic idea with REST is that you can attach a bunch of 'renderers' to different entities so that they can be available in different formats easily using the same HTTP verbs and url formats.
For more clarification on what RESTful means and how it is used google rails. Rails is a RESTful framework so there's loads of good information available in its docs and associated blog posts. Worth a read even if you arent keen to use the framework. For example: http://www.sitepoint.com/restful-rails-part-i/
RESTless means not restful. If you have a web app that does not adhere to RESTful principles then it is not RESTful
'RESTless' is a term not often used.
You can define 'RESTless' as any system that is not RESTful. For that it is enough to not have one characteristic that is required for a RESTful system.
Most systems are RESTless by this definition because they don't implement HATEOAS.
Any model which don't identify resource and the action associated with is restless. restless is not any term but a slang term to represent all other services that doesn't abide with the above definition. In restful model resource is identified by URL (NOUN) and the actions(VERBS) by the predefined methods in HTTP protocols i.e. GET, POST, PUT, DELETE etc.
Here are roughly summarized the key differences between RESTful and RESTless web services (it does not have to be strictly valid):
1. Protocol
RESTful services use REST architectural style,
RESTless services use SOAP protocol.
2. Business logic / Functionality
RESTful services use URL to expose business logic,
RESTless services use the service interface to expose business logic.
3. Security
RESTful inherits security from the underlying transport protocols,
RESTless defines its own security layer, thus it is considered as more secure.
4. Data format
RESTful supports various data formats such as HTML, JSON, text, etc,
RESTless supports XML format.
5. Flexibility
RESTful is easier and flexible,
RESTless is not as easy and flexible.
6. Bandwidth
RESTful services consume less bandwidth and resource,
RESTless services consume more bandwidth and resources.