Personal thoughts about the windows phone API

Usually I am writing about news according to my apps but today something more general and related to windows phone app development. So read this at your own risk, if you are not a developer. 🙂

Programing windows phone is done with the windows phone programing API (application programing interface). An API offers methods that can be called by „clients“ (an app), see: http://en.wikipedia.org/wiki/Api

In my opinion a good API is

1. Self-Explaining and simple to use, which means it’s easy to use for a developer without having to read much/any documentation.

For example the windows phone API offers a „SaveAppointmentTask“, which is really simple to use. An app developer can call this task with a single line of code. As a result a dialog is shown, where a user can enter the data of an appointment and tap the save icon – wow, a calendar app with one line of code. 😉

2. Hides Complexity

For example: You can turn on your TV and switch channels without any knowledge of how this is working internally. Your remote control is some kind of API. 😉

3. Allows you to do „more complex things“, if you really need to (yes, this is some contrast to 2.)

I will write more about this below…

4. Is extensive and allows you to do things you expect you can do with it

As a developer for a phone you may expect that the windows phone API offers some method to make phone calls, don’t you? 😉

5. Behaves „naturally“

For example a „ShowContact“ method shows details of a contact but does not delete the contact. 😉

I guess there are more things to add but let’s keep it with these.

What’s nice about the windows phone API?

Most API methods follow (1), which means they are simple to use and quite self-explaining. For example a „ShowMarketplaceTask“ opens the marketplace, a call to MessageBox.Show(„…“) shows some text on the screen.

To developers: I know, the first example is a „Task“ as called by MS and API in general may be something more „low level“ but this example should be easy to understand.

These examples also follow (2), they hide complexity. A developer does not need to care about the different screen resolutions, when he/she wants to show some text to the user. The MessageBox.Show() takes care of this by itself.

Of course these examples are very simple and I consider them as the minimum of what an API should provide.

What’s not so nice about the windows phone API?

In my opinion it fails at (3), which means it does not allow developers to do „more complex“ things?

Example:
A developer can call a „SaveAppointmentTask“, which shows the same dialog to create an appointment as the built in calendar but there is now way to customize this view in any way.

It’s not possible to add different „reminder times“ or change the user interface.

If you create an appointment in you windows live calendar by using your web browser, you can select different options for recurring events, for example an „end date“. This is not possible in the windows phone built in calendar and it also is not possible for developers to provide this option since extending the dialog which is shown on a call to „SaveAppointmentTaks“ cannot be edited/changed/configured in any way. 🙁

Providing a consistent way to create appointments in the built in calendar and in apps is a good thing but not allowing developers to customize or add options in my opinion fails according to (3).

Hint: Yes, I used this example since I am dealing exactly with these things in my app Week View

According to (4): When you open the built in calendar on your phone you can switch to the „Tasks“ page, which is a simple „ToDo“-List.

I wanted to integrate this in Week View for ages but there is no API for it. I don’t know why and can’t understand why MS “forgot” (?) this but it is not possible for third party developers to read, create or edit tasks. 🙁

Another example for (4): The WP 8.0 API has no methods to edit/remove existing calendar entries which was fixed by MS in WP 8.1.

 

What’s really bad in the windows phone API?

Of course this is my personal opinion but trust me: much more can be said here but I want to point out an example, I discovered a few days ago.

I wanted to add „lock screen integration“ to my app Week View.

An app can act as a lock screen provider and show text (and an icon) on the lock screen. On most windows phones the WP internal calendar is selected as lock screen text provider and as a result the subject of your next appointment is shown on the lock screen.

Theory: Let’s add this to Week View and extend it a bit (by allowing to filter by calendar type) and

In practice the API works this way: The text, which is shown on the lock screen must be assigned as a „wide live tile backside content“.

As you know, live tiles are the greatest invention 😉 on windows phone and they can have a front and a back side and can come in different sizes (small, medium, wide).

So if you are a developer and want your app to act as a provider for the lock screen text you need to

1. Extend the app manifest of your App
(basically telling the OS that app wants to show text on the lock screen)

2. Assign a text to the property „WideBackContent“ to the live tile, you create in your app.

BUT if you already use the back-side of the app live tile for some different stuff (like showing a graphical week representation or the next appointments, like Week View does), when you assign text to the „WideBackContent“ only this text is shown but the other content of your tile back-side is gone.

So in fact lock screen text integration can only be used, if your app does not have a wide live tile or at least does not want to show custom text/content on the live tile back side.

Sorry MS, but were the API designers drunken, when doing this?
Why not simply provide a text property that is independent from the live tile and which is only used for lock screen text?

There are some other serious bugs in the OS (like the live tile never updates, when the phone has no network connection) which were never fixed in WP 8.0 and fortunately are fixed in WP 8.1 and the API was extended in WP 8.1 too but the example above is something quite disappointing, if you are a windows phone developer.

Do some of my readers create windows phone apps their self?
Did you find some „WTF method/property“ in the API? 😉
Did you find a nice workaround? 😉