The "Flight Offers Search V2" and "Flight Offers Price V1" endpoints are returning errors. Probably it's a configuration issue
Flight Offers Search API comes with 2 different endpoints:
GET with a limited number of parameters but easier to implement for the most common use cases
POST version much more complete offering all types of filtering but it requires to build the JSON body. In that context we use a POST to offer the possibility to build the JSON body without length restriction, even if it is for a search. That's why in the swagger documentation you will find X-HTTP-Method-Override set at GET.
The Flight Offers Price API is built from the response of Flight Offers Search. To allow developers to reuse the body of the previous response we created this endpoint using the verb POST, That's why in the swagger documentation you will find X-HTTP-Method-Override set at GET.
Related
I have been working on designing an API that lets client create a product (think of product as something like website domain, something that comes into existence when client makes order for it to the service). Correspondingly with every purchase results in creation of the order object. Which means creation of two resources via a single POST request.
So afaik, the RFC standards recommends sending 201 on resource creation with URI for the resource in the Location header. But in the above scenario, we are creating two resources, domains and orders and I would want response to contain information related to both the resources.
Response would look something similar to this
POST /domains/
Request
body: {"domain_name": "awesome.com"},
Response
Body: {"order_id": "1234"}
Headers:
Location: http://example.com/awesome.com
But does not look very RESTful. I was wondering if there was a RESTful way to do this?
RFC 7231, section 6.3.2
The 201 (Created) status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. The primary resource created by the request is identified by either a Location header field in the response or, if no Location field is received, by the effective request URI.
The 201 response payload typically describes and links to the resource(s) created.
In other words, on the web we would solve your riddle by returning an HTML document that includes hyperlinks to all of the created resources, along with text to describe each, so that the client would know which new identifiers are available.
To make such a response machine readable, we would do the work of documenting the schema of the message, so that specialized clients would know how to identify the semantics of each of the provided links.
The same idea works if you replace HTML with a different media type (for example application/json). You define the schema, and then specialized clients can parse the response to find the identifiers that they need.
Of course, REST is largely about standardizing things so that we can use general purpose components; application/json is somewhat inadequate here, as it doesn't include a URI type (just strings, which are too general). So to be more "RESTful", you would choose one of the specialized JSON types that has a general purpose representation of a link.
Sookocheff's article On Choosing a Hypermedia Type.... is a decent starting point for the kinds of questions you will want to be considering.
I am creating API and trying to figure out is planned approach any good.
That API is not public and it will be used by SPA and mobile app that I build.So I am thinking of GraphQL-like design but without posting json and with regular HTTP methods.
Something like this for GET methods:
Example 1 - get users with specific fields(_join indicates sql table join), ordering and limit:api.com?table=users&displayFields=id,name,email,address,tel,country_join&orderBy=asc&orderColumn=name&offset=0&limit=10
Example 2 - get users based on search parameters with all fields, ordering and limit:api.com?table=users&search=John&searchFields=name,email&orderBy=asc&orderColumn=name&offset=0&limit=10
I assume this is bad since REST is standard, otherwise I would see much more examples of this approach.
But why is this bad? For me it seems easier to develop and more flexible to use.
Is proper REST API for examples I provided easier to implement, safer, easier to use or cache?
The main difference I see between putting the variables in the url vs the request body are:
the length of the data as the url length is limited while the request body is not
special characters to be escaped in the url which can lead to long and unclear url
These are 2 pros in favor of data in request body, but I agree that data in url is much simpler to test and use as tou don't need an http client tool like curl or postman to validate your endpoints.
REST however has stricter conventions if you want to fully implement it:
use the right http requests (get, post, patch, delete and put) to implement crud operations on one single endpoint
return the right http code as a result
use standard data format for input and output (json or XML)
For better interoperability between systems it's advised to comply with REST and microservices design patterns.
For small applications we can follow some shortcuts and not comply fully. I have integrated several services so far and each time I can tell you no one of them implements standard REST :-)
I'm designing a list endpoint for a resource that merits both full and light version of the resource called /transactions. By default, the response will include the complete resource, but there is also a need to provide clients with the "simplified" version of the resource list.
The first option is to use a custom param (e.g. /transactions?summary=true)
The second option is to use a custom endpoint, though not very RESTful (e.g. /transactions/summary)
The third option is to use content-type to allow a client to declare the alternative response body format. How would this look? (application/json+summary)? Are there any good examples of this being done?
Any other options come to mind?
The third option of using the Accept/Content-Type headers allows the media types to be a representation of a data, separate from the data itself.
A good example of this is github's API: https://developer.github.com/v3/media/
Which uses the http headers to allow clients to choose the format of the data, as well as the version. So in your case, the request could look something like:
curl http://api.host.com/transactions -H "Accept: application/summary+json"
And the response would contain a body of your simplified data format and the Content-Type header set to application/summary+json
If you want to be more pedantic about it, you could also use a vendor media type as application/vnd.yourcompany.summary+json. In this case, vnd implies that the media type is a vendor typically associated with application specific media types.
More Info:
Collection+JSON
A similar answer
A bit from restful API design
Here is an excerpt from an assignment I am currently doing:
Build a dummy app that:
Contains a REST API that operates over a single resource.
Contains a Backbone client that consumes that API and can list, show, create, update, and remove that resource.
My understanding was that the term "consume" implies total coverage of the API's exposed ressources. However, the assignment says "consumes that API and can [CRUD] that resource".
Is that sentence redundant or is my understanding of the term wrong?
(Bonus question: why searching Google for this question returns countless language-specific tutorials for "consuming an API" but none explain what the term actually means?).
To consume an API means to basically use any part of it from your application.
Consuming an API here means creating a client which can send requests to the API that you build.
It appears that you need to create and API which can handle Create, retrieve, update and delete (CRUD) of a resource. For instance if your REST api is to create a blog, your API should handle CRUD functions for the object/resource blogpost.
POST - Create a blog post
GET - Retrieve a blog post
PUT - Update a blog post
DELETE - Delete a blog post.
It is about the direction of the app's interaction with API - it either provides an API, or consumes it, so there are providers and consumers of API, and this is just a less general and ambiguous term than 'using'.
Simply consuming an API means using it in your application.
For, e.g., GET request to https://someapi/Users will give you all the users.
You need to request this URL https://someapi/Users to get all the users and then you can use it into your application.
I always think about Albert Einstein's quote of "If you can’t explain it to a six year old, you don’t understand it yourself." when someone asks a question that you might take for granted due to technical experience you have on a subject.
I think the following medium.com article does an excellent job explaining it: How do you explain API to a 5-year-old?
simply means : using the API.
You can do it with HTTP method (GET, POST, PUT, DELETE..) using something like Postman (Tool) or maybe you have a client app/library that calls these methods implicitly.
I'm building my first Rest API which serialize data to JSON and XML formats.
I would like to provide an index page to API clients, where they would be able to choose implemented endpoints.
What information do I need to include to make my API most useful, and how should I organize it?
That's a very complex question for a simple answer.
You may want to take a look at existing API frameworks, like Swagger Specification (OpenAPI), and services like apiary.io and apiblueprint.org.
Also, here's an example of the same REST API described, organized and even styled in three different ways. It may be a good start for you to learn from existing common ways.
https://api.coinsecure.in/v1
https://api.coinsecure.in/v1/originalUI
https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid
At the very top level I think quality REST API docs require at least the following:
a list of all your API endpoints (base/relative URLs)
corresponding HTTP GET/POST/... method type for each endpoint
request/response MIME-type (how to encode params and parse replies)
a sample request/response, including HTTP headers
type and format specified for all params, including those in the URL, body and headers
a brief text description and important notes
a short code snippet showing the use of the endpoint in popular web programming languages
Also there are a lot of JSON/XML-based doc frameworks which can parse your API definition or schema and generate a convenient set of docs for you. But the choice for a doc generation system depends on your project, language, development environment and many other things.