Our goal is to develop API where you can POST /data/save/ that will accept some JSON data like below. The main requirement that JSON should contain one of the following attributes:
"attribute1", "attribute2", "attribute3". Namely when one attribute is exist another one should not exist.
{
"name": "test name",
"attribute1": [
"test1", "test2"
]
or
"attribute2": [
"test3", "test4"
]
or
"attribute3": true
}
The question is how to correctly design such API that it will be easy to use and not confused from the client side.
It would be good to know some best practices in such direction.
I would return a
400 Bad Request
The request could not be understood by the server due to malformed
syntax. The client SHOULD NOT repeat the request without
modifications.
and a phrase explaining that multiple attributes are not supported.
I agree such API is confusing for client side.
What's about creating different endpoints:
POST /data/save/attribute1 json_1
POST /data/save/attribute2 json_2
A custom media type should clarify how to use your API. It should specify what to include in your request.
Another solution might be, building the request like this:
{
"name": "test name",
"attr-key": "my-attribute1",
"values": ["test1", "test2"]
}
Related
I think the answer to this question is great because it explains a lot about HAL: How to handle nested resources with JSON HAL?
However it does not fully answer the question (at least for me). Assuming we have a /employees resource that returns a list of all employees. I want the employees embedded but just with some basic information (not the full employee). This is OK according to the above answer and the spec. But how would my link look like?
So what would _links look like? Lets simplify the example. Assume there is no paging:
GET /employees
{
"_links": {
"self": { "href": "/employees" },
"employees" { "href": "/employees/{id}", "templated": "true" }
},
"_embedded": {
"employees": [{
"id": "1",
"fullname": "bla bli",
"_links": { ... }
},
{
"id": "2",
"fullname": "djsjsdj",
"_links": { ... }
}]
}
}
Does the templated "emloyees" URL make sense or would this be a case where you would not use any entry in _links? And if the URL is OK: is it necessary that the template parameter (here "id" does match the attribute in the embedded employee objects?
My heuristic is to consider the analogs in HTML - if it's OK for a web page, then it will also be OK for HAL.
"employees" { "href": "/employees/{id}", "templated": "true" }
What's the HTML analog? It's a form with a GET action. Can we have a form with a get action on a web page that also has digests of the information that will be reached via the form? Of course. So it must be fine here.
is it necessary that the template parameter (here "id") does match the attribute in the embedded employee objects?
I don't think it's necessary (the machines don't really care), but it's going to make life easier for the humans, and that alone has value.
Imagine, if you will, reading the documentation of a schema, and discovering that the same semantic concept (an identifier for an employee) has two different names with unrelated spellings. I would guess that would (a) introduce avoidable errors in the documentation when authors get confused about which spelling context they are in and (b) that's the sort of inconsistency that would make me suspicious of the quality of the specification as a whole.
But it's not impossible to have tradeoffs, and other benefits that outweigh these liabilities.
I'm just doing the preparation for an integration with EasyPost's Shipping API, which will be server side C#, but we always build a PostMan collection for new integrations, so that we can test data separately from the application if there's an issue.
While I do love the fact that EP provide C# libraries and examples, I'm struggling to find anything that just gives me a list of required headers and the raw JSON format for the body of any requests. It feels a bit like they're just being a little too helpful.
I'll be looking at the Orders endpoint probably.
I've got an account, I've checked all their documentation and searched the internet but haven't found anything so I'm hoping I'm not the first developer to want to use a client application for testing outside my code.
Update:
EasyPost now does have a public workspace https://www.postman.com/easypost-api
with at least 1 public collection
The curl examples are basically the same as json:
For the Address creation example:
-d "address[street1]=417 MONTGOMERY ST"
is the equivalent of
{ "address": { "street1": "417 MONTGOMERY ST" } }
(you might have to escape some characters to be valid json).
Check out How to stimulate cURL request to a request using postman for postman with HTTP Basic Auth.
EasyPost does not provide a public Postman collection; however, here is an example of a shipment Postman body (raw) that could be used. You can adjust the values, actions, objects, etc to your needs.
Using the following, you shouldn't need to pass any headers. You'll pass your API key under the username field with the Basic Auth authorization type.
{
"shipment": {
"to_address": {
"id": "adr_123..."
},
"from_address": {
"id": "adr_123..."
},
"parcel": {
"id": "prcl_123..."
},
"carrier_accounts": {
"id": "ca_123..."
},
"options": {
"address_validation_level": "0"
}
},
"format": "json",
"controller": "shipments",
"action": "create"
}
I'm having a hard time finding for the API in getting the contacts of the people who open the newsletter after sending it to a list of email. In the official API documentation of GetResponse, I didn't find a solution. Any idea or suggestion can help. thanks.
Though it's rather old now, I'll try to answer, maybe it helps someone.
Just as inside GetResponse web interface, you'll need to search contacts according to some criteria. These pages of the API docs describe how this is done:
http://apidocs.getresponse.com/v3/resources/search-contacts
Search contacts is the most complex part of the API. To save a search of contacts who opened a particular message you'll need to POST something like below to https://api.getresponse.com/v3/search-contacts/:
{
"name": "test_conditions", //can be any you like
"subscribersType": [
"subscribed" //can also be "undelivered", "removed" and "unconfirmed"
],
"sectionLogicOperator": "or", //or "and"
"section": [ //section can have up to 8 conditions; one saved search can have up to 4 sections
{
"campaignIdsList": [
"V" //you'll need to get campaigns' IDs with http://apidocs.getresponse.com/v3/resources/campaigns#campaigns.get.all
],
"logicOperator": "or",
"subscriberCycle": [
"receiving_autoresponder",
"not_receiving_autoresponder"
],
"subscriptionDate": "all_time", //"today", "yesterday", "this_month", "last_month", "this_week", "last_week" are also possible
"conditions": [
{
"conditionType": "opened",
"operatorType": "message_operator",
"operator": "autoresponder", //or "newsletter", or "split"
"value": "WTjXF" //message id, should be firstly got with a separate API call
}
]
}
]
}
More info on how the payload for such requests should be formed is here: http://apidocs.getresponse.com/v3/resources/search-contacts-reference
And the last point: if you don't need to save a search but only get the emails who've opened a message, in the object above you should remove the "name" property and post this to http://apidocs.getresponse.com/v3/search-contacts/contacts
More: http://apidocs.getresponse.com/v3/resources/search-contacts#search-contacts.contacts.form
i am trying to build POST-request for one CRM-system, building URL. I have the documentation wich shows methods for this CRM. In my case, i need to add contact, so they have the example of this method, required parameters in JSON.
fields:{
"NAME": "Mark",
"LAST_NAME": "Jonson",
"STATUS_ID": "NEW",
"ASSIGNED_BY_ID": 1,
"CURRENCY_ID": "USD",
"OPPORTUNITY": 12500,
"PHONE": [ { "VALUE": "555888", "VALUE_TYPE": "WORK" } ]
}
so i can successfuly add contact in my system, using this https://myportal.mycrm.com/rest/crm.contact.add?auth=xxxxxxxxxfields[NAME]=A&fields[LAST_NAME]=B
But i have a huge problem, adding a PHONE, because of its multiple parameters. So i was trying to do it in a lot of ways, for ex. fields[PHONE[0[VALUE]]]=345678&fields[PHONE[0[VALUE_TYPE]]]=WORK, but neither was success. Maybe someone can help me with it?
P.S. i need to do it only in URL, so it is not an option for me to use json-parsing, php, http-request-builder etc
Well, you are trying to make a POST-request, but what you've really done is GET-request. Please take a look.
I'm having trouble properly formatting one particular soap parameter using the node-soap module for node.js as a client, to a 3rd-party SOAP service.
The client.describe() for this method says this particular input should be in the shape of:
params: { 'param[]': {} }
I have tried a bunch of different JSON notations to try to fit my data to that shape.
Examples of formats that do NOT work:
"params": { "param": [ {"myParameterName": "myParameterValue"} ] }
"params": [ "param": { "name": "myParameterName", "_": "myParameterValue"} ]
"params": { "param" : [ {"name": "myParameterName", "_": "myParameterValue"} ] }
"params": { "param[]": {"myParameterName": "myParameterValue" } }
"params": { "param[myParameterName]": {"_": "myParameterValue" } }
I must be overlooking something, and I suspect I'm going to feel like Captain Obvious when some nice person points out what I'm doing wrong.
Here is what DOES work, using other soap clients, and how they handle the "named parameter with a value"
soapUI for this method successfully accepts this particular input via XML in the shape of:
<ns:params>
<ns:param name="myParameterName">myParameterValue</ns:param>
</ns:params>
Also, using PHP, I can successfully make the call by creating a stdClass of arrays like so:
$parms = new stdClass;
$parms->param = array(
array(
"name"=>"myParameterName","_"=>"myParameterValue"
)
);
and then eventually passing
'params' => $parms
to the PHP soap client
Many thanks!
To get a better look at what XML was being generated by node-soap, I added a console.log(message) statement to the node_modules/soap/lib/client.js after the object-to-XML encoding. I then began experimenting with various JSON structures to figure out empirically how they were mapping to XML structures.
I found a JSON structure for node-soap to generate the XML in my 3rd-party's required named-parameter-with-value format. I was completely unaware of the "$value" special keyword. Looks like this may have been added in the 0.4.6 release from mid-June 2014. See the change history
"params": [
{
"param": {
"attributes": {
"name": "myParameterName"
},
$value: "myParameterValue"
}
}
]
(note the outer array, which gives me the luxury of specifying multiple "param" entries, which is sometimes needed by this particular 3rd-party API)
generates this XML:
<tns:params>
<tns:param name="myParameterName">myParameterValue</tns:param>
</tns:params>
which perfectly matches the structure in soapUI (which I already knew worked) of:
<ns:params>
<ns:param name="myParameterName">myParameterValue</ns:param>
</ns:params>