I understand that vCard 4.0 will introduce some commonly used contact property fields (types) like GENDER, ANNIVERSARY, etc. There is no standard way to represent these in vCard 3.0 format.
My question is what should a client do if a vCard 3.0 object contains a GENDER type. Will that make it an invalid vCArd, or just that clients will ignore those fields?
Some clients will add a X-GENDER property. However, since it's an extended property, there's no guarantee that the application reading the vCard will detect it.
X-GENDER:Male
Source: http://en.wikipedia.org/wiki/VCard#vCard_extensions
You could also just go ahead and include a GENDER property, even though it's not part of the 3.0 specs. The specs say that if the vCard contains a property that the consumer does not recognize, the consumer must ignore that property and continue parsing the rest of the vCard.
Related
I have a resource, as an example a 'book'.
I want to create a REST POST endpoint to allow consumers to create a new book.
However, some of the properties are required and computed by API, and others were actually taken as they are
Book
{
name,
color,
author # computed
}
Let's say the author is somehow calculated in API based on the book name.
I can think of these solutions each has its drawbacks:
enforce consumer to provide the author and just filter it (do not take into account as an input) # bad because it is very unpredictable why the author was changed
allow the user to provide author # same problem
do not allow the user to provide an author and show an exception if the user provides it
The last solution seems to be the most obvious one. The main problem I can see is that it is inconsistent and can be bizarre for consumers to see the author later on GET request.
I want my POST endpoint to be as expressive as possible. So the POST and GET data transfer objects will look almost the same.
Are there any simple, expressive, and predictable patterns to consider?
Personally I'm a big fan of using the same format for a GET request as well as a PUT.
This makes it possible for a client to do a GET request, add a property to the object they received and immediately PUT again. If your API and clients follow this pattern, it also means it can easily add new properties to GET requests and not break clients.
However, while this is a nice pattern I don't really think that same expectation exists at much for 'creation'. There's usually many things that make less less to require as a property when creating new items (think 'id' for example), so I usually:
Define a schema for PUT and GET.
Define a separate schema for POST that only contains the relevant properties for creation.
If users supply properties not in the schema, always error with a 422.
some of the properties are required and computed by API
Computed properties are neither required nor optional, by definition. No reason to ask consumers to pass such properties.
do not allow the user to provide an author and show an exception if the user provides it
Indeed, DTO should not contain author-property. Consumers can send over network whatever they want, however it is the responsibility of the API-provider to publish contract (DTO) for consumers to use properly. API-provider controls over what properties to consider, and no exception should be thrown, as the number of "bad" properties that can be sent by consumers is endless.
So the POST and GET data transfer objects will look almost the same
Making DTOs of the same resource look the same is not a goal. In many cases, get-operation exposes a lot more properties than post-operation for the same resource, especially when designing domain-driven APIs.
Are there any simple, expressive, and predictable patterns to consider?
If you want your API to express the fact that author is computed, you can have the following endpoints:
POST http://.../author-computed-books
GET http://.../books/1
Personally, I wouldn't implement that way since it does not look natural, however you can get the idea.
I want my POST endpoint to be as expressive as possible. So the POST
and GET data transfer objects will look almost the same.
Maybe just document it instead of relying explicit stuff like it must be almost the same as the GET endpoint.
E.g. my POST endpoint is POST /number "1011" and my GET endpoint is GET /number -> 11. If I don't document that I expect binary and I serve decimal, then nobody will know and they would guess for example decimal for both. Beyond documentation another way of doing this and to be more explicit is changing the response for GET to include the base {"base":10, value:"11"} or changing the GET endpoint GET /number/decimal -> 11.
As of the computed author I don't understand how you would compute it. I mean either a book is registered and the consumer shouldn't register it again or you don't know much about the author of it. If the latter, then you can guess e.g. based on google results for the title, but it will be a guess, not necessarily true. The same with consumer data, but at least that is what the consumers provided. There is no certainty. So for me it would be a complex property not just a primitive one if the source of the information matters. Something like "author": {name: "John Wayne", "source": "consumer/service"} normally it is complex too, because authors tend to have ids, names, other books, etc.
Another thought that if it is weird for the consumers instead of expected, then I have no idea why it is a feature at all. If author guessing is a service, then a possible solution is making the property mandatory and adding a guessing service GET /author?by-book-name={book-name}, so they can use the service if they want to. Or the same with a completely optional property. This way you give back the control to the consumers on whether they want to use this service or not.
So I have my custom entity type, created it by following official tutorial:
https://docs.sulu.io/en/2.2/book/extend-admin.html
However entity I got is not translatable like i.e. standard pages or articles. I also didn't any info on how to make it translatable. Expected behavior is just to work as those standard types.
How to achieve that?
There are basically three things to do:
You have to add a new Translation entity for your custom entity. So if you have an Event entity, you need an additional EventTranslation entity. See https://github.com/sulu/sulu-workshop/tree/master/src/Entity
You need to tell Sulu, that your custom entity is translatable by adding the available locales to the view in your AppAdmin class, see https://github.com/sulu/sulu-workshop/blob/master/src/Admin/EventAdmin.php#L74
You need to adjust your custom entity's admin controller (it will receive a locale request parameter now) to persist the localized properties to the CustomEntityTranslation instead of the CustomEntity iself, see https://github.com/sulu/sulu-workshop/blob/master/src/Controller/Admin/EventController.php
So as conclusion, Sulu is only responsible for showing the locale switcher in the upper right corner and appending the current selected locale as locale parameter to your api calls. Everything else is completely up to you, you have to implement that like in a normal symfony application
At work (bank) we are re-designing our MW / Web services. We are using bottom-up approach to build those services. We are using Java, jax-ws. So I need to create rules to be followed. So I have 2 questions so far:
Should we create types to our objects fields, i.e. in class Client, should we create a CellPhone object or use simply string for that. I can see the pros & cons , object will be become heavy weight, but easy to validate & control.
Any other ideas ?
Should we be using SOAP built-in fault or create our own error status code (maybe in the SOAP header). I really like the SOAP fault because of the direct mapping to Java Exception.
Thanks in advance
Some answers:
1. Bare in mind that Web Services (I assume you're talking about SOAP-based WS, as you mentioned jax-ws and not jax-rs) use SOAP which is an XML based protocol.
2. For every class you create, you will have a type in your WSDL file.
3. The SOAP envelope (which holds the "body" of your message will also hold additional XML element to denote the cellphone - you're creating more traffic.
To conclude 1 - 3 and the fact you're talking about CellPhone, I don't understand why you need to have class for this.
Are you taking about a CellPhoen class that actually models a CellPhone (i.e - the cell-phone device, with properties like "vendor", "operator" ,etc..) or are you talking about the cell phone number? If this is just Cell-Phone number, then my recommendation, based on 1-3 is still valid.
To handle validation:
You can use many validator fameworks in order to validate phone number.
There is even a JSR in Java for validation.
I recommend you to look at here to read about the Hibernate-Validator framework which conforms to JSR 303.
You can also download the source of oVirt open source project ,
and take a look at oVirt-engine (look at ovirt-engine/backend/manager/modules/common) at our BusinessEntiies and see some "real life" examples on how to use these validators.
Regarding fault - you can create your own Faults, and map them to Java exceptions, I see no harm there.
Using WCF3.5SP1, VS2008. Building a WCF service that exposes about 10 service methods. We have defined about 40 [DataContract] types that are used by the service.
We now experience that adding an additional [DataContract] type to the project (in the same namespace as the other existing types) does not get properly exposed. The new type is not in the XSD schemas generated with the WSDL.
We have gone so far as to copy and rename an existing (and working) type, but it too is not present in the generated WSDL/XSD.
We've tried this on two different developer machines, same problem.
Is there a limit to the number of types that can exposed as [DataContract] for a Service? per Namespace?
No, there's no hard limit on the number of Data Contracts - mostly certainly not as low as 40 or 50!
What I'm guessing might be the problem is this: you can add as many DataContracts as you like - but unless they're actually being used (as an input parameter or return type of a service method), they won't be serialized into the WSDL/XSD.
What happens if you add another dummy service method which takes one of your newly added types, and returns an arbitrary INT value or something. Does it show up in the WSDL/XSD then??
ON what basis should we decide whether we have to create a dataContract or a MessageContract for my WCF services.
What I know is that when we need to have more control over SOAP,We use MessageContract.
Secondly I have seen some code in which DataContract is exposed through MessageContract.Whats the use of it.
Please provide some real life scenerios.
It's not an "either-or" question - you'll always have data contracts if you're dealing with compound data (more than just the basic types of int, string etc.). That's a given.
You'll only ever need message contracts if you need to very closely and very specifically control the layout of your SOAP messages. In most case, over 90% of the time - you don't.
A message contract allows you to specifically say which elements (scalar types or compound types as DataContracts) will be in the SOAP header, and which will be in the SOAP body.
You might need this if you have a communication partner which requires a very specific format and you have to tweak your SOAP messages to match that given layout exactly. That's just about the only valid scenario when you'll need to and should use message contracts.
So, to make a long story short: always use data contracts, practically never use message contracts (unless you absolutely, positively have to).
Marc
If you need to take over the SOAP headers and body explicitly, you would use MessageContracts. For example, if you needed to make sure a credit card number was encrypted in your message separately from the rest of your type, you'd need to get that level of control over the message on the wire.
Here's more information on that with some examples (specifically the encryption example): http://msdn.microsoft.com/en-us/library/ms730255.aspx
If you just want pure DTOs and don't care about their shape on the wire, go with DataContracts.