nationalbankbelgium/rest-api-design-guide

NBB's REST-ish API Design Guide

rest-api-design-guide's Issues

Identify a ressource by a composite key

Hi,

in our job we hav a resource that has a verion and for a business case the only identifier possible is a composite key so we came to these solutions.

1/ /myresource/code/version/
2/ /myresource?code=anycode&version=1
3/ /myresource/metacode with metacode=code+version

Several solutions appear on the internet, but we went for

2/ /myresource?code=anycode&version=1

that will return an array of 1 myresource

1/ /myresource/code/version => KO because /code/ is not an unique ID so it's not REST because url id should lead to a resource.

3/ /myresource/metacode => KO it's not clean as metacode is not really a property of the REST resource.

Did you have the case? How would you handle it?

Add HATEOAS support

Goal: provide explanations and examples in the design about discoverability, links generation, where and how links should be in the payloads. Refer to HAL.

Clarify on claims about security

Would you mind clarifying on this paragraph:

While that concept is appealing, it also has security implications. We always say that security by obscurity is not security, but providing attackers with full discoverability of your API is not necessarily wise.

What are you actually trying to express here? That hypermedia implies less security? That it implies security by obscurity? That discoverability implies less security?

Let me raise the counter question: if not though HATEOAS, how do you communicate security rules about which user is allowed to do what to clients and how is that approach more secure than the HATEOAS based approach?

Bulk update vs ETags

How should the client provide ETags when doing a bulk update/delete?

Create visualizations for the design workflow

Goal: visualize the design workflow and work it out further.

Integrate with contract-first approach..

File upload

Points yet to clarify:

• whether the charset matters and the impact it can have on requests going through infrastructure components / request interceptors
• whether the Content-Type matters (same reaons)

We currently recommend using the application/octet-stream as Content-Type and not necessarily specifying the charset (i.e., letting it default to us-ascii. Our reasoning is that in many cases, there should not be any interpretation of the content and it should be saved as is.

Although we need to check this regarding security.

Add support for embedding on retrieval via a query parameter

Goal: add support for an "_embed" query parameter for retrieval. Should embed related entities on demand

Section about compression

Goal: explain how to optimize for compactness

Clarify on the maturity level

You seem to misinterpret the semantics of the Richardson Maturity model. I clearly describes the REST architectural style as achieved if Level 3 is reached. The graphic is pretty precise on that. Also, note how the discussion of e.g. Level 0 describes the API to be an RCP one. So if — as you seem to imply — levels below 3 were already describing REST, that creates a contradiction.

Ironically, this is even directly stated in the summary of the article (emphasis mine):

I should stress that the RMM, while a good way to think about what the elements of REST, is not a definition of levels of REST itself. Roy Fielding has made it clear that level 3 RMM is a pre-condition of REST. Like many terms in software, REST gets lots of definitions, but since Roy Fielding coined the term, his definition should carry more weight than most.

Taking a step back, it seems what you're describing in the wiki is how to build decent HTTP APIs. That's just fine and probably a good thing to have if you have a lot of teams having to build these kinds of APIs. However, there's not need to label them REST if you're not actually adhering to the concept for two reasons:

1. If you tell people: "Here are our REST APIs", people will expect them to produce the qualities exposed by a REST API, e.g. evolvability. By skipping the parts of REST that actually produce those qualities, you basically disappoint your consumers.
2. You contribute to the wrong impression of what the architectural style of REST actually is, what it makes up.

I guess this makes me one of those "experts" that like to get into "religious discussions". I can live with that impression, but actually would just like to maintain semantics in technical terms as I wonder how are we supposed to really discuss things seriously if we're just bending every technological concept to what suits us or is en vogue these days.

Add design for nested filtering

See https://dzone.com/articles/dynamically-filter-json-with-jackson-and-squiggly?edition=292930&utm_source=Daily%20Digest&utm_medium=email&utm_campaign=dd%202017-04-26

https://github.com/bohnman/squiggly-filter-jackson

Search: better support for advanced search

Question: Why is GET specified as SHOULD be safe

I can see why you can't guarantee that GET is idempotent, as the resource could change and GET on a collection is likely to be even more volatile, but why does the specification allow it to be not safe?

Internationalization: support the definition of multiple languages via the URL

You MAY also support the definition of multiple languages just like with the Accept-Language header.

Design for this approach?