Credit Invoices and Switching from Tags to Codes

[luxflux]

Credit Invoices

This allows one to manage debit and credit invoices via /api/invoices.

Specifying the type of an invoice is done by providing type ('credit' or 'debit') upon creation. It is not possible to update the type. It is not possible anymore to update the customer (for a debit invoices) or company (for a credit invoice).

Switch from tags to codes to reference accounts

Unfortunately we cannot use tags to reference accounts. When returning the line items of an invoice, we cannot know the tag which has been used to reference the accounts and if its unique. This prevents updates to an invoice or bookings as the update call expects tags for referencing.

As codes are unique and also more intutive than the id of an account, they're a way better choice to use than tags.

[luxflux]

@huerlisi IMHO this is finished for the time being, do you mind reviewing it?

[huerlisi]

Some general remarks:

While the data model for debit and credit invoices are the same (and I think that makes some sense), I think having two dedicated API endpoints still make sense. Similar to the way we have UI controllers for them. But you're currently implementing an API consumer, so you know best. It's the restrictions like 'Specifying the type of an invoice is done by providing type ('credit' or 'debit') upon creation. It is not possible to update the type.' or the slightly different attributes (customer...) that let me think they should have dedicated endpoints. We might also add dedicated actions for them ('send', 'print' for debit as example)

Regarding tags vs. IDs vs. code. I see the issue with tags. They make most sense for BookingTemplates and auto generated Bookings for invoices etc. where we want to select the account by function. But as you say they are failure prone when doing API calls to updates. Using the code on the other hand is very handy to build API calls that can be understood by the coder or a application designer writing specs with it's accountant.

But I'd go with IDs in most of the API calls for Bookings and Invoices. It's how the data model is built and will never introduce inconsistencies. I think it makes sense to allow creating Bookings with account 'codes' or maybe even 'tags'. But only as API glue, so the coder has one-to-one way to implement the requirements. And to spare another API call to get the ID of the Account. But we should always allow using IDs for the account relation and always return them IMHO.

[luxflux]

While the data model for debit and credit invoices are the same (and I think that makes some sense), I think having two dedicated API endpoints still make sense. Similar to the way we have UI controllers for them. But you're currently implementing an API consumer, so you know best. It's the restrictions like 'Specifying the type of an invoice is done by providing type ('credit' or 'debit') upon creation. It is not possible to update the type.' or the slightly different attributes (customer...) that let me think they should have dedicated endpoints. We might also add dedicated actions for them ('send', 'print' for debit as example)

I totally agree on this one. I first created two different API endpoints, only to find out that the only difference is the switching of company_id and customer_id. Maybe we can do something similar as we have for the people endpoint.

But I'd go with IDs in most of the API calls for Bookings and Invoices. It's how the data model is built and will never introduce inconsistencies. I think it makes sense to allow creating Bookings with account 'codes' or maybe even 'tags'. But only as API glue, so the coder has one-to-one way to implement the requirements. And to spare another API call to get the ID of the Account. But we should always allow using IDs for the account relation and always return them IMHO.

I always like to look at the API of GitHub to get some ideas about API design. They don't use IDs to identify users, repos and organisations (they only provide it in their response). Which I really like as it allows you to get started easily. IMHO exposing the ids would expose too some of the internal structure which isn't necessary. Codes are unique like an id with the advantage that you may reuse them. Exposing ids and codes would also create some more edge case we have to handle (e.g. Client provides a code and an id for the debit account but they aren't of the same account).

So, what do you think? I'd go with codes only for everything Account related. Also if we ever implement CRUD endpoints for Account.

[huerlisi]

Okay, I'm convinced. This is probably the reason there is a dedicated API instead of simply using the CRUD resources with JSON;-)

Are there more changes? Otherwise it's good to merge.

Thanks!

[luxflux]

@huerlisi I don't see anymore changes coming... Do you push the button? :smile:

[huerlisi]

:shipit: