Is that possible to analyze the request (based on queries) on swagger hub api 3.0?
For example, I need to reproduce the next thing.
For request getUser?id=1 swager swagger has to send response to client
{
"user_id": "1"
"user_name": "Alex",
}
For request getUser?id=2 swager swagger has to send response to client
{
"user_id": "2"
"user_name": "Bob",
}
If that possible, could you help me with this please?
I guess your question is about SwaggerHub mock server. According to the documentation, this is not supported:
Note that the mock does not support business logic, that is, it cannot send specific responses based on the input.
Related
I'm just wondering if there is a way to add a Recorded Time in Communication Phone Call using the API?
Okay I just found it in the documentation Activity Endpoint.
https://app.clio.com/api/v4/documentation#operation/Activity#create
Sounds like you managed to answer your own question, but for anyone dealing with the same or similar issue, I thought I would throw in my two cents.
This is really a two step operation:
Create the Communication log through a POST request to /api/v4/communications.json endpoint.
Create an activities entry associated with the communication you just created through a POST request to /api/v4/activites.json.
After you create the communication, you can get the ID back for the record you just made. Using that, you create a new Activity record, and as part of the payload, you include the ID in the following.
{
"data": {
"communication": {
"id": 0
},
"quantity": $time_qty,
"date": "YYYY-MM-DD",
"type": "TimeEntry"
}
}
We are building an API which will be used for inserting and updating the records in a database. So if the record exists based on the Key the record will be updated and if it does not then it will be inserted.
I have two questions.
As per REST guidelines, what are the options for designing such an API e.g. PUT / POST OR PATCH? How should the list of objects be represented?
NOTE: I know from other answers that I read that there is confusion over how it should be as per REST guidelines. So I am OK if I can get some guidance on general best practice (irrespective of REST part)
Secondly, the part where I am really confused about is how to represent the output of this or what this API should return.
Specific guidance/inputs on above topic would be really appreciated.
I've seen many different implementations for inserts/updates across various vendors (Stripe, HubSpot, PayPal, Google, Microsoft). Even though they differ, the difference somehow fits well with their overall API implementation and is not usually a cause for stress.
With that said, the "general" rule for inserts is:
POST /customers - provide the customer details within the body.
This will create a new customer, returns the unique ID and customer details in the response (along with createdDate and other auto-generated attributes).
Pretty much most, if not all API vendors, implement this logic for inserts.
Updates, are quite different. Your options include:
POST
POST /customer/<customer_id> - include attributes and values you want to update within the body.
Here you use a POST to update the customer. It's not a very common implementation, but I've seen it in several places.
PUT
PUT/customer/<customer_id> - include either all, or partially updated attributes within the body.
Given PUT is technically an idempotent method, you can either stay true to the REST convention and expect your users to provide all the attributes to update the resource, or make it simpler by only accepting the attributes they want to update. The second option is not very "RESTful", but is easier to handle from a users perspective (and reduces the size of the payload).
PATCH
PATCH /customer/<customer_id> - include the operation and attributes that you want to update / remove/ replace / etc within the body. More about how to PATCH.
The PATCH method is used for partial updates, and it's how you're "meant" to invoke partial updates. It's a little harder to use from a consumers perspective.
Now, this is where the bias kicks-in. I personally prefer to use POST, where I am not required to provide all the attributes to invoke an update (just the ones I want to update). Reason is due to simplicity of usage.
In terms of the response body for the updates, usually they will return object within the response body include the updated attributes (and updated auto-generated attributes, such updatedDate).
Bulk inserts/ updates
Looking at the Facebook Graph HTTP API (Batch Request) for inspiration, and assuming POST is your preferred method for updates, you could embed an array of requests using a dedicated batch resource as an option.
Endpoint: POST /batch/customers
Body:
{
["first_name": "John", "last_name": "Smith"...], //CREATE
["id": "777", "first_name": "Jane", "last_name": "Doe"...], //UPDATE
["id": "999", "first_name": "Mike", "last_name": "Smith"...], //UPDATE
[....]
}
Sample Response
{
"id": "123",
"result":[
{ // Creation successful
"code": 200,
"headers":{..},
"body": {..},
"uri": "/customers/345"
},
{ // Update successful
"code": 200,
"headers":{..},
"body": {..},
"uri": "/customers/777",
},
{ // A failed update request
"code": 404,
"headers":{..},
"body": {..}, // body includes error details
}
]
}
How do I implement count, group by, and other commonly used SQL constructs using GET REST API calls and still adhering to good standards? I haven't seen any documentation that describes how to do this. Are there any standards already in place? Any help would be appreciated. Thanks.
From the other answer, I think you are looking for this:
POST /books/search
{
"keywords": "...",
"yearRange": {"from": 1945, "to": 2003},
"genre": "..."
}
There is nothing un-RESTful about this endpoint. It accepts data
(entity) in the form of the request body. That data is the Search
Criteria - a DTO like any other. This endpoint produces a resource
(entity) in response to the request: Search Results. The search
results resource is a temporary one, served immediately to the client,
without a redirect, and without being exposed from some other
canonical url.
It's still REST, except the entities aren't books - the request entity
is book search criteria, and the response entity is book search
results.
Look at this answer for more details: https://stackoverflow.com/a/31984477/37083
Using this structure you can easily expand the search with other complex items
POST /books/search
{
"keywords": "...",
"yearRange": {"from": 1945, "to": 2003},
"genre": "...",
"groupby": "year",
"countby": "keywords"
}
If we have customers and orders, I'm looking for the correct RESTful way to get this data:
{
"customer": {
"id": 123,
"name": "Jim Bloggs"
"orders": [
{
"id": 123,
"item": "Union Jack Keyring",
"qty": 1
}, {
"id": 987,
"item": "London Eye Ticket",
"qty": 5
}
]
}
}
GET /customers/123/orders
GET /customers/123?inc-orders=1
Am I correct that the last part/folder of the URL, excluding query string params, should be the resource returned..?
If so, number 1 should only return order data and not include the customer data. While number 2 is pointing directly at customer 123 and uses query string params to effect/filter the customer data returned, in this case including the order data.
Which of these two calls is the correct RESTful call for the above JSON..? ...or is there a secret number 3 option..?
You have 3 options which I think could be considered RESTful.
1)
GET /customers/12
But always include the orders. Do you have a situation in which the client would not want to use the orders? Or can the orders array get really big? If so you might want another option.
2)
GET /customers/123, which could include a link to their orders like so:
{
"customer": {
"id": 123,
"name": "Jim Bloggs"
"orders": {
"href": "<link to you orders go here>"
}
}
}
With this your client would have to make 2 requests to get a customer and their orders. Good thing about this way though is that you can easily implement clean paging and filtering on orders.
3)
GET /customers/123?fields=orders
This is similar to your second approach. This will allow clients to use your API more efficiently, but I wouldn't go this route unless you really need to limit the fields that are coming back from your server. Otherwise it will add unnecessary complexity to your API which you will have to maintain.
The Resource (identified by the complete URL) is the same, a customer. Only the Representation is different, with or without embedded orders.
Use Content Negotiation to get different Representations for the same Resource.
Request
GET GET /customers/123/
Accept: application/vnd.acme.customer.short+json
Response
200 OK
Content-Type: application/vnd.acm.customer.short+json
{
"customer": {
"id": 123,
"name": "Jim Bloggs"
}
}
Request
GET GET /customers/123/
Accept: application/vnd.acme.customer.full+json
Response
200 OK
Content-Type: application/vnd.acme.customer.full+json
{
"customer": {
"id": 123,
"name": "Jim Bloggs"
"orders": [
{
"id": 123,
"item": "Union Jack Keyring",
"qty": 1
}, {
"id": 987,
"item": "London Eye Ticket",
"qty": 5
}
]
}
}
The JSON that you posted looks like what would be the result of
GET /customers/123
provided the Customer resource contains a collection of Orders as a property; alternatively you could either embed them, or provide a link to them.
The latter would result in something like this:
GET /customers/123/orders
which would return something like
{
"orders": [
{
"id": 123,
"item": "Union Jack Keyring",
"qty": 1
},
{
"id": 987,
"item": "London Eye Ticket",
"qty": 5
}
]
}
I'm looking for the correct RESTful way to get this data
Simply perform a HTTP GET request on a URI that points to a resource that produces this data!
TL;DR
REST does not care about URI design - but on its constraints!
Clients perform state transitions through possible actions returned by the server through dynamically identified hyperlinks contained within the response.
Clients and servers can negotiate on a preferred hypermedia type
Instead of embedding the whole (sub-)resource consider only returning the link to that resource so a client can look it up if interested
First, REST does not really care about the URI design as long as the URI is unique. Sure, a simple URI design is easier to understand for humans, though if compared to HTML the actual link can be hidden behind a more meaninful text and is thus also not that important for humans also as long as they are able to find the link and can perform an action against it. Next, why do you think your "response" or API is RESTful? To call an API RESTful, the API should respect a couple of constraints. Among these constraints is one quite buzzword-famous: hypertext as the engine of application state (HATEOAS).
REST is a generalized concept of the Web we use every day. A quite common task for a web-session is that a client requests something where the server sends a HTML document with plenty of links and other resources the client can use to request further pages or stream a video (or what ever). A user operationg on a client can use the returned information to proceed further, request new pages, send information to the server etc, etc. The same holds true for RESTful applications. This is was REST simply defines as HATEOAS. If you now have a look at your "response" and double check with the HATEOAS constraint you might see that your response does not contain any links to start with. A client therefore needs domain knowledge to proceed further.
JSON itself isn't the best hypermedia type IMO as it only defines the overall syntax of the data but does not carry any semantics, similar to plain XML which though may have some DTD or schemas a client may use to validate the document and check if further semantic rules are available elsewhere. There are a couple of hypermedia types that build up on JSON that are probably better suited like f.e. application/hal+json (A good comparison of JSON based hypermedia types can be found in this blog post). You are of course entitled to define your own hypermedia type, though certain clients may not be able to understand it out of the box.
If you take f.e. a look at HAL you see that it defines an _embedded element where you can put in certain sub-resources. This seems to be ideal in your case. Depending on your design, orders could also be a resource on its own and thus be reachable via GET /orders/{orderId} itself. Instead of embedding the whole sub-resource, you can also just include the link to that (sub)resource so a client can look up the data if interested.
If there are cases where you want to return only customer data and other cases where you want also to include oder data you can f.e. define different hypermedia types (based on HAL f.e.) for both, one returning just the customer data while the other also includes the oder data. These types could be named like this: application/vnd.yourcompanyname.version.customers.hal+json or application/vnd.yourcompanyname.version.customer_orders.hal+json. While this is for sure an development overhead compared to adding a simple query-parameter to the request, the semantics are more clear and the documentation overhead is on the hypermedia type (or representation) rather then the HTTP operation.
You can of course also define some kind of view structure where one view only returns the customer data as is while a different view returns the customer data including the orders similar to a response I gave on a not so unrelated topic.
I have this following scenario in my application. I am logged in as a user and i create a group. There is a REST api for creating the group (POST /groups/api/v1/groups) and getting the group details (GET /groups/api/v1/groups/{group id})
The response returned on success is not just the json representation of the group resource. Its a DTO which contains a lot of other information (to avoid multiple calls to the server)
For instance, the response can include
Actions that can be performed on the group (for ex: inviting a user to the group) and the corresponding urls that need to be hit for each action
Count of members in the group.
Recent activity in the group
Member information
etc
Right now the only client using the REST api's is the UI which needs additional information. If the APIs are exposed to developers later, they may not need all the information being returned. How do we handle rest responses in such scenarios where we have to return DTO's which contain more information?
Is it a good design to be returning dto's in rest response for GET or should be avoided?
It helps if you accept the fact that RESTful HTTP is noisy. The design compensation for the noise is caching, which you should try to use as much as you can to save server hits. A well-cached application can use multiple resources, rather than one large resource, because many of the requests will not ever leave the client.
As far as your specific question, use the expand query parameter to identify what child objects to include. You can further specify what properties of that child to include. For example,
GET /groups/api/v1/groups/12345
{
"id": 12345,
"name": "The Magnificent Seven",
"location": {
"self": "/groups/api/v1/locations/43"
}
}
GET /groups/api/v1/groups/12345?expand=location
{
"id": 12345,
"name": "The Magnificent Seven",
"location": {
"self": "/groups/api/v1/locations/43",
"longitude": "24°01′N",
"latitude": "104°40′W"
}
}
GET /groups/api/v1/groups/12345?expand=location[latitude]
{
"id": 12345,
"name": "The Magnificent Seven",
"location": {
"self": "/groups/api/v1/locations/43",
"latitude": "104°40′W"
}
}
Well giving more data than required can prove to be harmful and you need to start explaining everyone why you are giving so much data. You can have a query param that is secret to a subset of users say "alldetails=true" which will give the full DTO.
If you are using Java with codehaus or some other JSON utility on the REST server you can specify what elements to expose by using a mixin. codehaus has "addMixInAnnotations()" for that.
A good REST response for GET should have an identifier, required details and URLs in JSON or XML.