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)
Related
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.
Say I provide a REST API at:
https://mycompany.com/api/v1
And GETting https://mycompany.com/api/v1/user/<userID> will return information about a user with that user ID (if it exists).
What would be the correct terminology for /user/<userID>?
I have considered the term 'endpoint' however it could be used to mean both the general REST API endpoint at https://mycompany.com/api/v1 and the specific resource's endpoint at https://mycompany.com/api/v1/user/<userID>. I would like to be as specific as possible.
Edit: updated /users to /user as poster below notes.
I found this question because I was also wondering about this exact same thing.
Then I found this article by ThoughtWorks: REST API Design - Resource Modeling.
It uses the terminology "collection resource" vs "singleton resource", which I find helpful.
Example:
# collection resource:
/customers
# singleton resource
/customers/id-123
In contrast to commenters above, I would actively encourage you to use pluralized resource names everywhere to be consistent in your semantics, but I guess we can agree to disagree there.
Endpoint is /users in your case.
/users/id
is a resource and naming can changes according to your request method. (post/get/fetch/put etc). To sum up, it is resource of the endpoint. this resource may be useful for you
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)
We have 2 developers who have conflicts in the way to design the RESTful API Endpoint. Basically, let say that we have Facebook product in hand, one table for the posts.
First developer give the opinions that
We should seperate Endpoint by product, not by the technical storage. To be like that, we will have endpoint for user facebook post and other facebook post.
/v1/wall/mypost
/v1/wall/other
To be like that, we be able to configure each products that may return difference results
Second developer disagree, give the opinions that
If be like that, it will make infinite endpoint. it will have /wall/someone, /wall/sometwo.
We should have single endpoint, and just let that be a part of query. ex. /wall?user=someone, /wall?user=sometwo
The endpoint should be look like technical schema, it return the same result, why it have to seperated to make it more jobs on maintenance the code.
What is the good practice to design our endpoint? Is it should be endpoint by the product? or is it should be by schema?
It should depend on what 'resource' that the service is suppose to manage from the API user perspective and not from the internal implementation.
With that, if the service is to manage say, a resource that can be identified by 'someone', 'sometwo' and, then the correct way to model it is
/wall/someone/
/wall/sometwo/
In this case, 'someone' and 'sometwo' are two different resources and you could have infinite # of them; but that has nothing to do with the internal storage or implementation.
On the backend, there should be some url pattern to extract 'someone' and 'sometwo' as resource and map them into internal implementation details.
What are these "endpoints" you speak of? That's SOAP terminology! RESTful web services are defined in terms of "resources" that are uniquely identified by URL.
A resource typically represents an entity in your domain model (e.g., a user). The ID of the entity is typically used as a path element ("path parameter" in the lingo of most REST libraries, such as JAX-RS) in the URL. Query parameters should only be used to sort/filter results on the server side.
Your first developer is closer to being correct.
I'm reasonably sure I understand the server-side of HATEOAS design - returning state URL's in the response - but I'm slightly confused about how to design a client to accept these.
For instance, we access a resource at //somehost.com/resource/1 - this provides us with the resource data and links. We'll assume POST to //somehost.com/resource is returned, indicating a 'new' action. Now I understand posting some data to that url creates a new resource, and provides a response, but where does the form to post that data reside? I've seen implementations where //somehost.com/resource/1/new provides a form which POSTS to /resource, but that URL itself contains a verb, and seems to violate REST.
I think my confusion lies in that I'm implementing a RESTful API and a client to consume it, within the same application.
Is there some sort of best-practice for this sort of thing?
I've seen implementations where //somehost.com/resource/1/new provides a form which POSTS to /resource, but that URL itself contains a verb, and seems to violate REST.
This is incorrect. A URI containing a verb does not, in itself, violate any REST constraint. It is only when that URI represents an action that this becomes a violation. If you can perform a GET request on the URL and receive some meaningful resource (such as a "create new resource" form), then that is perfectly RESTful, and good practice.
My own API is exactly as you describe: /{collection}/new returns a form. /new is just shorthand for a hypothetical /new-resource-creation-form and still represents a noun, and only supports GET requests (HEAD, OPTIONS and TRACE not withstanding).
What HATEOAS prohibits is the user agent being required to know, that in order to create a new resource, it must add /new to the name of the collection.
Basically, if you implement your API as (X)HTML, and can surf it in a browser and perform all actions (AJAX may be required for non-POST form submissions until HTML and browsers catch up with HTTP), then it complies with the hypermedia constraint of REST.
EDIT promoted from comments:
As long as the response negates any need for a priori knowledge, it conforms to the hypermedia constraint. If the client claims to understand HTML, and you send back a response containing a link to an external stylesheet or javascript (no matter where that is hosted) which the client needs to be able to render the page correctly, then it is reasonable to say that the constraint is met. The client should know how to handle all media types it claims to support. A normal human web browser is the perfect example of a client with no out-of-band knowledge about any one HTTP service (web site).
Just to say it explicitly, a web site is a kind of HTTP service. Web browsers do not treat different web sites differently. In order to search for products on Amazon, you load the Amazon service endpoint at http://amazon.com/ and follow links or fill out forms provided in that response. In order to search for products on eBay, you load the eBay service endpoint at http://ebay.com/ and do the same.
Browsers don't know in advance that for searching eBay you must do this, but for searching Amazon you have to do that. Browsers are ignorant. Clients for other HTTP services should be ignorant too.
Yes, you could provide a URI that returns a form for resource creation. Conceivably the form could be used for dynamic discovery of the elements needed to construct a new resource (but you'd want to decide how practical that would really be in a machine-to-machine environment).
Unless there is a requirement that somehow the API has an exact browser-surfable equivalent, the documentation of the media type will describe what elements are needed.
Remember that documentation of media types and the allowed HTTP verbs for a resource is not contrary to RESTful principles. Look at the SunCloud API for an example.
Indeed, according to your example, POST'ing to
//somehost.com/resource
to create a new resource is more standard than first returning a form
//somehost.com/resource/1/new
and THEN POST'ing to
//somehost.com/resource
anyway.