I am working on REST APIs.
can REST API post/put can include request parameters without a request payload?
where I can find the standard REST specifications
There are no "standard REST specifications". REST is defined by Roy Fielding's thesis Architectural Styles and the Design of Network-based Software Architectures. The HTTP verbs POST and PUT are defined in rfc 2616. REST doesn't necessarily mean a HTTP transport - it is an architectural style which is well suited to web based APIs. Part of that style is that the definition of a service is determined entirely by the contents of messages passed, specifically the way they contain references to other parts of the service (i.e. hyperlinks). As such, if it makes sense for your API to create an empty resource an empty PUT request would be a reasonable way to do it.
Related
When I read the documents about what the REST is, one of what they always say is that REST api should be stateless. Here, I feel a bit awkward, since just plain HTTP is also stateless.
Since REST can be said it's a special architecture using HTTP protocols, it seems redundant to say that REST should be stateless.
Does the word 'stateless' means the same thing in both REST and HTTP?
If not please tell me the difference
I'm not asking the meaning of stateless in http, but difference of stateless in rest and http
Does the word 'stateless' means the same thing in both REST and HTTP?
Yes.
The reason that they are the same is that HTTP is a consequence of REST.
Since 1994, the REST architectural style has been used to guide the design and development of the architecture for the modern Web -- Fielding, 2000.
Prior to his dissertation, Fielding was an author of RFC 2068 and RFC 2616.
Just for clarification, could you tell me what '"the principles that are now called REST were refined through Fielding's work on HTTP.' means?
Section One of Reflections on the REST Architectural Style includes a timeline: the first implementations of HTTP were in 1990-91, Fielding started participating in 1993. During the specification process (RFC 1945, RFC 2068, RFC 2616) Fielding developed an "HTTP Object Model" that later came to be understood as the "REST Architectural Style".
The first edition of REST was developed between October 1994 and August 1995, primarily as a means for communicating Web concepts as we wrote the HTTP/1.0 specification and the initial HTTP/1.1 proposal. -- Fielding
Which is to say, the ideas of REST evolved in parallel with the standardization of HTTP, to serve as an oracle: how can we evaluate whether a proposal will damage or destroy the important properties of the web?
Section 6.3.4 of the thesis describes the consequences of some mismatches that were standardized.
Stateless in HTTP terms means that each request has no knowledge of any prior request, i.e, there is no built-in mechanism in HTTP to track who is making requests and the effects of those requests.
In terms of RESTful services, it means that each request doesn't rely on state, e.g., saved client info, to fulfill a request -- all information needed to fulfill a request is enclosed in the request message (the CRUD operation, resource in question, auth tokens, app platform identification, etc.).
This means that your RESTful API should be guarded by a layered architecture that governs authentication, session management, and other non-RESTful operations.
In this context, both RESTful services and HTTP should operate under the same constraints: statelessness (as defined above).
It may seem intuitive to design a REST API like this, but you'd be surprised of the close-couplings found at the core of many REST services:
GET /users/:id
if authenticated and authorized //not stateless
send User resource
To combat this, most HTTP frameworks provide middleware layers.
Helpful REST-design questions:
What is idempotency in HTTP methods?
REST stands for Representational State Transfer which means that the state is representational. Request tracking mechanism or Session is not preserved on the api server. The state of a request may be transferred to other api servers.
Moreover the convention like GET /users/:id states that each resource has a identification mechanism in built in the url thus there is no need to track the resources in a request as the URL itself contains the client resource request information eg: GET /users/1, PUT /users/1.
If I am calling a Web APi service and that service makes various other calls to other services, do I use POST or GET?
To elaborate further, let's say I call Web Api Service One saying 'Do the thing'. Web Api One's job when requested thus, is to GET data from Service Two and POST data to Service Three. Perhaps Service One will then update Service Two. Service One will then respond to caller with any success/failure.
My question again is should I the caller, use POST or GET to Service One?
It's all about the semantics of the request. From the RFC 7231:
The request method token is the primary source of request semantics;
it indicates the purpose for which the client has made this request
and what is expected by the client as a successful result.
Here's a brief description of some HTTP methods defined in the RFC RFC 7231 (click the links to check the full method definition):
GET: Transfer a current representation of the target resource.
HEAD: Same as GET, but only transfer the status line and header section.
POST: Perform resource-specific processing on the request payload.
PUT: Replace all current representations of the target resource with the request payload.
DELETE: Remove all current representations of the target resource
In addition to the methods listed above, the RFC 5789 standardized the PATCH HTTP method for performing partial updates to a resource.
POST is commonly seen as a "catch all" method, once the target resource process the request payload according to the resource's own specific semantics.
HTTP methods can be classified as safe and/or idempotent and it must be taken into account when designing an API with on the top of HTTP.
Typically I would only use a variety of HTTP verbs (GET, POST, PUT, DELETE etc) when using a REST API. Then the endpoints are resources in their own right. For example:
/car
So the verbs make sense (are you getting a car? creating one? updating one? removing one?)
But when I am not using a REST API the HTTP verbs tend to have less meaning and I generally only use HTTP POST. Otherwise you hit logical problems like you're experiencing here.
eg
/rentacar
This API models an RPC that may cause many resources to change in many ways. It is not a REST API and so the HTTP Verbs don't really relate.
But in honesty, for RPC (remote procedure calls), people choose between GET and POST by either:
GET for operations that don’t modify anything and POST for other cases.
GET for operations that don’t need too much parameters and POST for other cases.
GET and POST on a random basis or always use POST.
Purists prefer 1. But sometimes you don't know when modifications are going to occur. So, take your pick!
Is there a name for one piece of an API?
For example, say I have an API the offers four services:
getCustomerInfo
setCustomerInfo
getProductInfo
setProductInfo
Then say, I want to tell a colleague:
The API is going to need a fifth webhook?
I know this is an incorrect use of the word webhook.
What is the correct terminology?
Thanks!
UPDATE: This might be a duplicate. krishna kanth's answer here: What is an Endpoint? is:
The term Endpoint was initially used for WCF services. Later even
though this word is being used synonymous to API resources, REST
recommends to call these URI (URI[s] which understand HTTP verbs and
follow REST architecture) as "Resource".
In a nutshell, a Resource or Endpoint is kind of an entry point to a
remotely hosted application which lets the users to communicate to it
via HTTP protocol.
I think the word you're looking for is resource. I also think that getting and setting would be combined under a single resource and the HTTP calls to that resource would define whether you are GETing or PUTing (setting in REST using HTTP).
I think in general an API is a set of methods of communication between various software components.
So, I would say:
The API is going to need a fifth method?
Wikipedia also defines API and methods here:
https://en.wikipedia.org/wiki/Application_programming_interface
Roy Thomas Fielding defines it as Resource Identifier in your dissertation for the degree of Doctor of Philosophy (see Architectural Styles and the Design of Network-based Software Architectures).
According Roy Fielding:
REST uses a resource identifier to identify the particular resource
involved in an interaction between components.
I believe you can use the resource identifier /product do handle the product resource and the resource identifier /customer to handle the customer resource. Also, use the appropriated HTTP method to do the desired action. For example:
PUT to /product/{id} to edit a product resource identified by {id} (instead of setProductInfo)
GET to /product/{id} to return a representation of a product resource identified by {id} (instead of getProductInfo)
TutorialsPoint defines the following methods in context of RESTful design:
URI HTTP Body Result
-----------------------------------------------------------------
listUsers GET empty Show list of all the users
addUser POST JSON string Add details of new user
deleteUser DELETE JSON string Delete an existing user
:id GET empty Show details of a user
I think this is misleading, because it's not RESTful.
A RESTful design would be as following:
URI HTTP Body Result
----------------------------------------------------------------
users GET empty Show list of all the users
users POST JSON string Add details of new user
users DELETE empty Delete an existing user
users/:id GET empty Show details of a user
Is my understanding of RESTful correct?
Regardless of definition of RESTful, in my opinion, TutorialsPoint presented wrong design, because deleteUser inside URL duplicates information that is already passed as DELETE HTTP action, which violates universal principle of Once And Only Once.
The first set of endpoints is a bad design for a REST API. It's all about RPC (and DELETE requests should not have a payload).
The second set of endpoints are resource-orientated and that's what you want in a REST API. The URI identifies the resource and the HTTP method expresses the operation over the resource.
However the REST architecture goes much beyond the URIs design.
The REST architectural style is protocol independent, but it's designed over the HTTP protocol most of the time.
The fundamental concept in a RESTful application is the resource. And resources can have different representations. For more details, this answer can be helpful.
To be considered RESTful, an application must follow a set of constraints defined in the chapter 5 of Roy Thomas Fielding's dissertation:
Client-server
Stateless
Cache
Uniform interface
Resources identification
Resources representation
Self-descriptive messages
Hypermedia
Layered system
Code-on-demand
Yes your understanding is correct. That tutorial is misleading.
I am new to RESTful APIs and everywhere I read that REST APIs "must be hypertext-driven". I have googled a lot but haven't found a concrete explanation of the concept. So:
In practical terms, what does it mean that REST APIs should be 'hypertext-driven'?.
When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects action. Roy T. Fielding - http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
It is about one of the fundamental constraints of REST architectural style - Hypermedia As The Engine Of Application State (HATEOAS). It means that in any given moment, client, based on hypermedia in representation of current resource, must have all the information he needs to decide where to transit next(change its Application State). That hypermedia controls in hypertext connect resources to each other, and describe their capabilities in machine-readable ways. A REST client just needs to know one thing in order to communicate with REST server - understanding of hypermedia. Opposite, in a service-oriented architecture(SOA), clients and servers interact through a fixed interface shared through documentation or an interface description language (IDL).
HATEOAS decouples client and server so that they can be developed separately.
For example,
If you make an initial call to a rest service to add a customer using some URL /customers/ then you will get a response back (consider the customer is successfully added),
HTTP/1.1 201 Created
Location: http://www.myREST/customers/<uuid>/
Now the client who made the call to add customer knows how to find the corresponding customer from the link returned as a response header.
You may ask how does client know that he can make POST to /customer/. By different means - hypermedia controls, DSL specific formats and profiles.
REST mean that api follow correct use for HTTP Verbs, Status code, etc. HTTP protocol, has verbs like: GET, POST, PUT, OPTIONS and DELETE. In a rest api, each verb is map to specific action on resource. For example:
POST is allways create a new instance of resource; GET is get the resource (or a list), DELETE is allways remove resource associated; PUT is modify/update a exist resource .....
Plus, you should use the status code for indicate response : 201 to create, 200 to modify, etc.
You can take more information on http://restinpractice.com/book/ (Jim Weber book)