<div dir="ltr"><div><span style="font-size:13px">> I think a cleaner payload would be: ...</span><br></div><div><span style="font-size:13px"><br></span></div><div><span style="font-size:13px">Unless I overlooked something the two example payloads are identical. Regardless I agree that current JSON responses could be improved. </span></div><div><span style="font-size:13px"><br></span></div><div><span style="font-size:13px">However in this particular case I am not sure whether "duplicities" are an issue. The </span><span style="font-size:13px">requested resources (services) just </span>happened to have the same parent<span style="font-size:13px">. Also extracting these duplicities would mean that resources listed under .../services and /services/{id} would be different, which doesn't make sense as the former is just a list of all services available after providing {id} as part of the url.</span></div><div><span style="font-size:13px"><br></span></div><div><span style="font-size:13px">For my point of view a possible issue is the use of "id" attributes -- such attributes lack semantics and resource urls should be used instead (as it allows transition between resources) [1]. Nevertheless there is a plenty of APIs which are using ID attributes so I would consider this to be of minor importance.</span><br></div><div><br></div>> <span style="font-size:13px">When an organization is created, seems like organizationId is </span><span style="font-size:13px">derived from organizationName? What's the purpose of two fields </span><span style="font-size:13px">uniquely identifying an organization?</span><div><span style="font-size:13px"><br></span></div><div><span style="font-size:13px">As you said, id is </span><span style="font-size:13px">derived not copied -- some characters (such as whitespace) are removed or replaced, thus the value of both fields can be different. Name is meant for human users to read, id as a system identifier. </span></div><div><span style="font-size:13px"><br></span></div><div><span style="font-size:13px">> </span><span style="font-size:13px"> </span><span style="font-size:13px">Can id, name, description attributes for service be renamed to </span><span style="font-size:13px">serviceId, serviceName, serviceDescription?</span></div><div><span style="font-size:13px"><br></span></div><div><span style="font-size:13px">The requested resource is list of all services. I would kinda assume that all attributes (unless something indicates otherwise) are attributes of service object. So what would be the point of making the attribute names more complicated? Again changing the attributes here would require to mirror these changes to .../services/{id} </span><br></div><div><span style="font-size:13px"><br></span></div><div><span style="font-size:13px">[1] Interesting presentation about REST api design. Unfortunately author mixed in some Czech for no reason. The important stuff is in English though. </span><a href="https://speakerdeck.com/honzajavorek/rest-api-manual">https://speakerdeck.com/honzajavorek/rest-api-manual</a></div><div><br></div><div>Jakub. </div></div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Jul 23, 2015 at 12:49 AM, Arun Gupta <span dir="ltr"><<a href="mailto:arun.gupta@gmail.com" target="_blank">arun.gupta@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Moving to swagger will be good!<br>
<br>
Can reasonable defaults be assumed? For example, not setting<br>
endpointType currently sets it to null. It'll be convenient if it is<br>
assumed it to be "rest". That is going to be the most common use case<br>
anyway. How does the processing differ if the endpointType is set to<br>
"soap"?<br>
<br>
Another question ...<br>
<br>
Accessing the list of services for an organization as:<br>
<br>
curl --user admin:admin123! -H "Accept: application/json"<br>
<a href="http://192.168.99.103:8082/apiman/organizations/everest/services" rel="noreferrer" target="_blank">http://192.168.99.103:8082/apiman/organizations/everest/services</a><br>
<br>
And the generated payload is:<br>
<br>
[{"organizationId":"everest","organizationName":"everest","id":"catalog","name":"catalog","description":"catalog<br>
service","createdOn":1437575090081},{"organizationId":"everest","organizationName":"everest","id":"order","name":"order","description":"order<br>
service","createdOn":1437575867804},{"organizationId":"everest","organizationName":"everest","id":"user","name":"user","description":"user<br>
service","createdOn":1437575649446}]<br>
<br>
A few issues with this ...<br>
<br>
- Why organizationId and organizationName are repeated with each<br>
service? I think a cleaner payload would be:<br>
<br>
[{"organizationId":"everest","organizationName":"everest","id":"catalog","name":"catalog","description":"catalog<br>
service","createdOn":1437575090081},{"organizationId":"everest","organizationName":"everest","id":"order","name":"order","description":"order<br>
service","createdOn":1437575867804},{"organizationId":"everest","organizationName":"everest","id":"user","name":"user","description":"user<br>
service","createdOn":1437575649446}]<br>
<br>
- When an organization is created, seems like organizationId is<br>
derived from organizationName? What's the purpose of two fields<br>
uniquely identifying an organization?<br>
<br>
- Can id, name, description attributes for service be renamed to<br>
serviceId, serviceName, serviceDescription?<br>
<br>
Thanks,<br>
Arun<br>
<br>
On Wed, Jul 22, 2015 at 10:17 AM, Eric Wittmann<br>
<div class="HOEnZb"><div class="h5"><<a href="mailto:eric.wittmann@redhat.com">eric.wittmann@redhat.com</a>> wrote:<br>
> Fair questions all.<br>
><br>
> - Everything is optional in the payload so that you can set individual<br>
> properties without sending *everything*<br>
> - Only the 'gateways' has a default value - but it will default only if<br>
> there is a single gateway installed in apiman. if multiple gateways have<br>
> been configured, then you must pick one<br>
><br>
> We'll likely be moving the API documentation over to swagger at some point,<br>
> replacing the miredot docs.<br>
><br>
> -Eric<br>
><br>
> On 7/22/2015 9:02 AM, Arun Gupta wrote:<br>
>><br>
>> Here is the inbound payload for<br>
>><br>
>> <a href="http://localhost:8080/apiman/organizations/organizationId/services/serviceId/versions/version" rel="noreferrer" target="_blank">http://localhost:8080/apiman/organizations/organizationId/services/serviceId/versions/version</a>:<br>
>><br>
>> {<br>
>> endpointType:rest | soap<br>
>> publicService:boolean<br>
>> endpointProperties:{<br>
>> string =>string<br>
>> }<br>
>> gateways:[<br>
>> {<br>
>> gatewayId:string<br>
>> }<br>
>> ]<br>
>> plans:[<br>
>> {<br>
>> version:string<br>
>> planId:string<br>
>> }<br>
>> ]<br>
>> endpoint:string<br>
>> }<br>
>><br>
>> How do I know which parts of optional? Why "gateways" is an array of<br>
>> objects instead of array of string?<br>
>><br>
>> Can there be defaults assumed if nothing is specified in the payload?<br>
>> For example, make the service public by default, use rest type, assign<br>
>> no plan, and have no endpoint properties.<br>
>><br>
>> Created <a href="https://issues.jboss.org/browse/APIMAN-559" rel="noreferrer" target="_blank">https://issues.jboss.org/browse/APIMAN-559</a> for syntax highlighter.<br>
>><br>
>> Arun<br>
>><br>
>> On Wed, Jul 22, 2015 at 8:33 AM, Eric Wittmann <<a href="mailto:eric.wittmann@redhat.com">eric.wittmann@redhat.com</a>><br>
>> wrote:<br>
>>><br>
>>> There is a feature request already in JIRA for allowing the POST (create<br>
>>> new<br>
>>> service version) to include all of the same information that a PUT would<br>
>>> allow. A future version will allow this.<br>
>>><br>
>>> <a href="https://issues.jboss.org/browse/APIMAN-427" rel="noreferrer" target="_blank">https://issues.jboss.org/browse/APIMAN-427</a><br>
>>><br>
>>> Which optional parts are not indicated?<br>
>>><br>
>>> -Eric<br>
>>><br>
>>> On 7/21/2015 10:19 PM, Arun Gupta wrote:<br>
>>>><br>
>>>><br>
>>>> POST on<br>
>>>><br>
>>>> <a href="http://localhost:8080/apiman/organizations/{organizationId}/services/{serviceId}/versions" rel="noreferrer" target="_blank">http://localhost:8080/apiman/organizations/{organizationId}/services/{serviceId}/versions</a><br>
>>>> takes only:<br>
>>>><br>
>>>> {<br>
>>>> version:string<br>
>>>> cloneVersion:string<br>
>>>> clone:boolean<br>
>>>> }<br>
>>>><br>
>>>> and returns all the information about the created endpoint, including<br>
>>>> all the information that needs to be set later by calling PUT on<br>
>>>><br>
>>>><br>
>>>> <a href="http://localhost:8080/apiman/organizations/{organizationId}/services/{serviceId}/versions/{versionId}" rel="noreferrer" target="_blank">http://localhost:8080/apiman/organizations/{organizationId}/services/{serviceId}/versions/{versionId}</a>.<br>
>>>><br>
>>>> Was there discussion about taking in the relevant information as part<br>
>>>> of original POST request?<br>
>>>><br>
>>>> Also, optional JSON parts are not indicated in the payload. How can<br>
>>>> that be done?<br>
>>>><br>
>>>> Can an appropriate syntax highlighter be used?<br>
>>>><br>
>>>> Arun<br>
>>>><br>
>>>> On Tue, Jul 21, 2015 at 6:11 PM, Eric Wittmann<br>
>>>> <<a href="mailto:eric.wittmann@redhat.com">eric.wittmann@redhat.com</a>><br>
>>>> wrote:<br>
>>>>><br>
>>>>><br>
>>>>> It depends on a number of variables. But basically for each service<br>
>>>>> you<br>
>>>>> want to create you'll need at least:<br>
>>>>><br>
>>>>> 1) create the service<br>
>>>>> 2) create version of the service<br>
>>>>> 3) update version with the desired settings (endpoint info, plans, etc)<br>
>>>>> 4) publish version (pushes it to the gateway)<br>
>>>>><br>
>>>>> That would be for a public service with no policies.<br>
>>>>><br>
>>>>> If you want to configure it with policies, then there are extra calls<br>
>>>>> for<br>
>>>>> that. If you wanted to add a service definition (swagger) then there's<br>
>>>>> a<br>
>>>>> separate call for that. Etc.<br>
>>>>><br>
>>>>> You'll of course need an organization to hold the services. You also<br>
>>>>> need<br>
>>>>> to create and lock plans if you intend to use multiple plans. If you<br>
>>>>> use<br>
>>>>> plans (vs. public services) you'll need to create applications and then<br>
>>>>> contracts between the apps and the service(s). :)<br>
>>>>><br>
>>>>> -Eric<br>
>>>>><br>
>>>>> On 7/21/2015 5:06 PM, Arun Gupta wrote:<br>
>>>>>><br>
>>>>>><br>
>>>>>><br>
>>>>>> This is helpful!<br>
>>>>>><br>
>>>>>> What is the minimum number of calls required for registering endpoints<br>
>>>>>> for a few services?<br>
>>>>>><br>
>>>>>> Arun<br>
>>>>>><br>
>>>>>> On Tue, Jul 21, 2015 at 7:11 AM, Eric Wittmann<br>
>>>>>> <<a href="mailto:eric.wittmann@redhat.com">eric.wittmann@redhat.com</a>><br>
>>>>>> wrote:<br>
>>>>>>><br>
>>>>>>><br>
>>>>>>><br>
>>>>>>> There is a test plan in apiman that does all of this. It can be<br>
>>>>>>> found<br>
>>>>>>> here:<br>
>>>>>>><br>
>>>>>>><br>
>>>>>>><br>
>>>>>>><br>
>>>>>>> <a href="https://github.com/apiman/apiman/blob/master/test/suite/src/main/resources/scripts/api-manager-testPlan.xml" rel="noreferrer" target="_blank">https://github.com/apiman/apiman/blob/master/test/suite/src/main/resources/scripts/api-manager-testPlan.xml</a><br>
>>>>>>><br>
>>>>>>> Each of the tests in the XML file is executed in order, starting with<br>
>>>>>>> this<br>
>>>>>>> one:<br>
>>>>>>><br>
>>>>>>><br>
>>>>>>><br>
>>>>>>><br>
>>>>>>> <a href="https://github.com/apiman/apiman/blob/master/test/suite/src/main/resources/data/orgs/001_create-test.resttest" rel="noreferrer" target="_blank">https://github.com/apiman/apiman/blob/master/test/suite/src/main/resources/data/orgs/001_create-test.resttest</a><br>
>>>>>>><br>
>>>>>>> The format of each *.resttest file is:<br>
>>>>>>><br>
>>>>>>> VERB /path/to/API/resource user/pass<br>
>>>>>>> Request-Header-1: value<br>
>>>>>>> Request-Header-2: value<br>
>>>>>>><br>
>>>>>>> {<br>
>>>>>>> "json" : "payload"<br>
>>>>>>> }<br>
>>>>>>> ----<br>
>>>>>>> expectedResponseCode<br>
>>>>>>> Expected-Response-Header-1: value<br>
>>>>>>> Expected-Response-Header-2: value<br>
>>>>>>><br>
>>>>>>> {<br>
>>>>>>> "expected-json" : "response-payload"<br>
>>>>>>> }<br>
>>>>>>><br>
>>>>>>> So basically you would be interested only in what is above the "----"<br>
>>>>>>> separator.<br>
>>>>>>><br>
>>>>>>> You are right - we should write a blog post or document a hello world<br>
>>>>>>> use-case.<br>
>>>>>>><br>
>>>>>>> -Eric<br>
>>>>>>><br>
>>>>>>><br>
>>>>>>> On 7/20/2015 7:11 PM, Arun Gupta wrote:<br>
>>>>>>>><br>
>>>>>>>><br>
>>>>>>>><br>
>>>>>>>><br>
>>>>>>>> Is there a sample that shows the complete creation/order of<br>
>>>>>>>> organization, services, endpoints, etc using the REST API?<br>
>>>>>>>><br>
>>>>>>>> The documents at [1] are helpful but a Hello World sample would be<br>
>>>>>>>> very useful. I started creating a sample at [2].<br>
>>>>>>>><br>
>>>>>>>> [1] <a href="http://www.apiman.io/latest/api-manager-restdocs.html" rel="noreferrer" target="_blank">http://www.apiman.io/latest/api-manager-restdocs.html</a><br>
>>>>>>>> [2]<br>
>>>>>>>><br>
>>>>>>>><br>
>>>>>>>><br>
>>>>>>>> <a href="https://github.com/arun-gupta/microservices/blob/master/microservice/docker/Dockerfile" rel="noreferrer" target="_blank">https://github.com/arun-gupta/microservices/blob/master/microservice/docker/Dockerfile</a><br>
>>>>>>>><br>
>>>>>>>> Cheers,<br>
>>>>>>>> Arun<br>
>>>>>>>><br>
>>>>>>><br>
>>>>>><br>
>>>>>><br>
>>>>>><br>
>>>>><br>
>>>><br>
>>>><br>
>>>><br>
>>><br>
>><br>
>><br>
>><br>
><br>
<br>
<br>
<br>
</div></div><span class="im HOEnZb">--<br>
<a href="http://blog.arungupta.me" rel="noreferrer" target="_blank">http://blog.arungupta.me</a><br>
<a href="http://twitter.com/arungupta" rel="noreferrer" target="_blank">http://twitter.com/arungupta</a><br>
</span><div class="HOEnZb"><div class="h5">_______________________________________________<br>
Apiman-user mailing list<br>
<a href="mailto:Apiman-user@lists.jboss.org">Apiman-user@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/apiman-user" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/apiman-user</a><br>
</div></div></blockquote></div><br></div>