nationalbankbelgium / rest-api-design-guide Goto Github PK
View Code? Open in Web Editor NEWNBB's REST-ish API Design Guide
License: Other
NBB's REST-ish API Design Guide
License: Other
Points yet to clarify:
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.
Goal: provide explanations and examples in the design about discoverability, links generation, where and how links should be in the payloads. Refer to HAL.
How should the client provide ETags when doing a bulk update/delete?
Goal: explain how to optimize for compactness
Goal: add support for an "_embed" query parameter for retrieval. Should embed related entities on demand
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?
Goal: visualize the design workflow and work it out further.
Integrate with contract-first approach..
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?
You MAY also support the definition of multiple languages just like with the Accept-Language header.
Design for this approach?
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:
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.
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?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.