I am writing my first RAML for a Mule project and had a query around naming convention. At the moment I have a requirement where a customer will make a single payment. So I have a /payment resource. If a new requirement to be able to make multiple payments was introduced later how would the resources be shown in RAML?
Will the resource for a single payment look like POST:/payments/payment
I have been told that the paths should be no more than 4 levels so I think the above standard would easily go above 4 levels in some cases and also I may repeat GET and POST etc under each single and plural resource name with the one difference being the request being a collection instead of just an object.
Also, if I was looking at resources for e.g. a customer's order should I include the order resource e.g.
GET: /customer/{customerId}/order/{orderId}
or is it best practice to go straight to the orderId?
GET: /customer/{customerId}/{orderId}
Finally, when should I use a parameter instead or a resource URI?
I see alot of examples on the web but not much on conventions so far so just wanted to check my understanding is correct so not to have a rewrite in the future.
Thanks
This link is good resource. http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
There is no established rule i think, I follow plural all the time and singularity is contextual based on the service call.
GET: /customers/ - Get all consumers
GET: /customer/{customerId} - Gets singular customer
is it best practice to go straight to the orderId?
It is best practice to to highlight relation between the resources as customers//orders//items// ..
singular uses for singleton resource, which returns a single object, for example users/{userID}/adress. HTTP methods:
GET/HEAD(get) ✅
POST(create) ❌
PUT(replace) ✅
PATCH(Partial update) ✅
DELETE(remove) ❌
plural uses for collection resource, which returns a list of the objects, for example users/{userID}/orders/ HTTP methods:
GET/HEAD(get) ✅
POST(create) ✅
PUT(replace) ❌
PATCH(Partial update) ✅ used for batch update objects in the collection
DELETE(remove) ❌
entity uses as subresource with id in the collection resource, for example users/{userID}. HTTP methods:
GET/HEAD(get) ✅
POST(create) ❌
PUT(replace) ✅
PATCH(Partial update) ✅
DELETE(remove) ✅
Related
There're 2 properties for my terraform resource and one of them can be updated but the other can't so I want to mark it as immutable but when I open https://github.com/hashicorp/terraform-plugin-sdk/blob/main/helper/schema/schema.go#L37, it seems like there's no such an option.
Can I mark a property as immutable in Terraform resource anyhow?
Based on your question I think you are asking about a provider you are developing, rather than a Terraform module written against an existing provider.
Lots of remote APIs have object properties that are fixed once the object is created, but preventing them from changing altogether would violate Terraform's declarative model, and so the typical way to represent this in providers is for the provider to respond to a change on such an attribute by reporting that it can't make that change without replacing the object, which is to say: destroying the existing object and creating a new one to replace it.
In the Terraform SDK there's a convenient attribute for the common case that any value change requires replacement: if you set ForceNew: true then the SDK will automatically notice if there's a change to the value of that attribute and report back to Terraform that the change is impossible without replacing the object. Terraform will then ask the provider to plan to create a new object instead, and present the result to the user as a planned action where the resource instance "must be replaced", with an annotation attached to the argument whose change prompted that proposal.
In some rarer cases the rules are more complicated, such as it being possible to change values in certain ways but not in other ways. For example, if a resource type is representing a virtual disk then it might be possible to grow the disk without replacing it, but not possible to shrink it. In that case, you can use the resource-level CustomizeDiff function to specify some custom logic for making the decision, calling ResourceDiff.ForceNew conditionally if e.g. the change to the disk size indicates that the new value is less than the old value.
You can think of the ForceNew: true attribute-level setting as a convenience shorthand for the more general CustomizeDiff approach, which suffices for most common situations.
If you mean an attribute, let's say I want to ignore changes to tags in a resource, then use
lifecycle {
ignore_changes = [
# Ignore changes to tags, e.g. because a management agent
# updates these based on some ruleset managed elsewhere.
tags,
]
}
How PIP and whole ABAC engine should behave in case if it can't resolve attributes.
There are several cases:
Destination object using which we are resolving attribute is not found
Attribute can't be resolve because provided attributes not sufficient to request addition information. Like if we passed single userId and resource name without id.
If during attributes resolution chain (when some attributes depends from another) something has been missing that make target attribute resolution impossible.
ABAC is a broad concept that does not specify this kind of low-level behavior; and it is difficult to give a universal best practice for all ABAC frameworks, since there is a growing bunch of them possibly quite different: some of them are standard (eg. OASIS XACML, NIST NGAC), others non-standard yet generic (eg. OPA), others product-specific (eg. Kubernetes ABAC).
It is easier to give tips for the XACML (3.0) standard since the specification is more mature:
§ 5.29 says: In the event that no matching attribute is present in the context, the MustBePresent attribute governs whether this element returns an empty bag or “Indeterminate”. See Section 7.3.5. (The MustBePresent is defined on AttributeDesignator elements in your XACML Policy. An AttributeDesignator is a reference to an attribute, for which, in your case, a PIP should be called if the attribute is not available in the current request context.)
§ 7.3.5 gives more details: If the attribute is missing, then MustBePresent governs whether the attribute designator or attribute selector returns an empty bag or an “Indeterminate” result. If MustBePresent is “False” (default value), then a missing attribute SHALL result in an empty bag. If MustBePresent is “True”, then a missing attribute SHALL result in “Indeterminate”. This “Indeterminate” result SHALL be handled in accordance with the specification of the encompassing expressions, rules, policies and policy sets. If the result is “Indeterminate”, then the AttributeId, DataType and Issuer of the attribute MAY be listed in the authorization decision as described in Section 7.17. However, a PDP MAY choose not to return such information for security reasons. [...] Regardless of any dynamic modifications of the request context during policy evaluation, the PDP SHALL behave as if each bag of attribute values is fully populated in the context before it is first tested, and is thereafter immutable during evaluation. (That is, every subsequent test of that attribute shall use the same bag of values that was initially tested.) The last sentence means in particular that if PIP attribute resolution results in an empty bag and MustBePresent=False, you should keep the attribute value as empty bag for the rest of the policy evaluation, i.e. NOT try to call the PIP again for the same attribute (risking a value change) in the same context.
§ 7.19.3 specifies how the PDP should include the information about a missing attribute in its response.
Beware that the final result is also affected by combining algorithms in XACML. E.g. even if an AttributeDesignator returns Indeterminate because of a PIP error in a child Rule/Policy(Set), algorithms of the enclosing policy like deny-unless-permit (resp. permit-unless-deny) may return Deny (resp. Permit) regardless.
That's what the standard says, then, there is implementation-specific behavior. In AuthzForce XACML implementation for instance, we distinguish the following cases while trying to be as XACML compliant as possible:
If PIP internal error occurs during attribute resolution (connection issues, misconfiguration, missing dependency, etc.), then the AttributeDesignator evaluates to Indeterminate regardless of MustBePresent, because we consider this critical, and we add the info Missing attribute XXX; we also add info about the cause, e.g. Missing dependency: attribute YYY if PIP requires some attribute that was missing from the context to do its job (e.g. missing dependency: attribute 'subject-id' if the PIP fetches the user's roles but requires the subject-id attribute to do that, which is missing).
If PIP attribute resolution is done error-free but no value found, in other terms the result is empty (e.g. some PIP fetches the user's roles successfuly from a database but gets an empty list because no role has been assigned to the user.), then the AttributeDesignator evaluates to an empty bag if MustBePresent=false, else (if MustBePresent=true) returns Indeterminate with the info Missing attribute XXX.
The interaction between the PDP and the PIP is not specified in the XACML standard. It is down to each implementation (AuthZForce, Axiomatics...) to determine how they handle each case.
Generally speaking, there are 3 errors that can occur when using a PIP:
Connection issues: the target PIP (e.g. an LDAP server) cannot be reached
Mapping configuration issues: the mapping for the attribute is invalid. For instance you are retrieving an attribute from a non-existing SQL table or column.
Data issue: there is no data to be read in the underlying source
In addition, there is another possible issue: the keys used in the mapping (e.g. username) has no value at all. In this case, it is clear that the mapping (e.g. to retrieve a role) will not be invoked at all.
Points 1 and 2 could lead to Indeterminate. This helps the administrator troubleshoot the installation.
Point 3 should lead to NotApplicable for that branch that uses the attribute. If there is no value, then so be it. Why would there necessarily be a value?
I hope this helps,
David.
I am using a JSON Schema to validate a file. This is somehat similar to an XML XSD.
I have a few questions concerning the id field.
Does the schema still works without network connection ?
The URL in the id should be accessible from a web browser ? i.e. if 'id' = "https://example.com/question", does this mean that we should be able to access the schema from a browser by going to https://example.com/question ?
I am a bit lost on this subject. I know that it is best practice to have an id property as a unique identifier for every schema, and that this gets most useful when creating a complex schema with different schemas that reference each other.
But I am not sure if we need to assign a URL to the id field or not. And I'm also lost concerning the implication of having this URL for the schema.
Thank you very much for your help
Main purpose of id ($id since draft-06) is to organize scope for $ref resolving.
$id does not have to be an existing HTTP resource. Identified schema can be even defined in another one (example in spec test suite).
JSON Schema spec expects that validator should be able to resolve references based on $ids defined in current schema. Remote references should be also resolved, but there are no limitations on how exactly it should happen.
In many cases network interactions during validations are very unwanted due to high latency. Most implementations provide you a way to preload/define schema resources by $id explicitly before validation.
According to spec root schema SHOULD have $id which is an absolute URI, but whether or not it should be accessible with HTTP client is up to you and your validator.
$id is only defined to be an URI.
http://json-schema.org/draft-07/json-schema-core.html#rfc.section.8.2
See RFC-3986 Uniform Resource Identifier (URI): Generic Syntax
https://www.rfc-editor.org/rfc/rfc3986
"A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource."
A nice write-up by Daniel Messier provides a clear explanation of the nature of an URI - which can just be an URN - but may also be a valid URL
https://danielmiessler.com/study/url-uri/
I would like to create work order using escalation once the asset is moved to some other location (like REPAIR) using move/modify. I do understand that we can trigger CREATEWO however I am not sure on how to set the values on some fields in work order like worktype, workact , etc. Also I am unable to pick the correct record which has performed move modify ( unable to fetch the exact record using ASSETTRANS table).
Let me know if anyone has done this before, thanks in advance!
It sounds like you have an Escalation calling an Action that calls the AppAction CREATEWO. Assuming that's correct..
First, create a Relationship in DB Config between the ASSET object and WORKORDER that will find the most recent work order against this asset. You can look at the NEWWORKORDER relationships on WORKORDER and TICKET as an example. For reference, I will assume you name this relationship MYNEWWORKORDER.
Next, create some Actions against the ASSET object that use MYNEWWORKORDER.<ATTRIBUTENAME> in the Parameter/Attribute field, where <ATTRIBUTENAME> is the name of the attribute (e.g. WORKTYPE) you want to supply a value for in the Value field.
Once that is done, create an Action of type Action Group where CREATEWO is the first member and the Actions you just made are the succeeding members.
Finally, update the Escalation to call your new Action Group instead of the numbered one that the Escalation application created for you.
I am migrating my grammar from version 3 to 4. I recognize that version 4 has listeners and visitors and I plan to use them, but hope to do the migration piece meal. I want to leave actions intact in my grammar for the time being.
I am using a custom token, and specify it using TokenLabelType in the option section of the grammar. However, the generated code uses a 'match()' method which doesn't get promoted to my custom token, causing the java compilation to fail.
I also noticed the 'start' property of a token is not promoted to the custom token type either.
Is there something else I should do to properly use custom tokens in my code?
If memory serves, Ter posted a design document on the Antlr.org site that outlines the differences between Antlr3 and 4 (cannot seem to find it at the moment).
In any case, make sure your custom token extends org.antlr.v4.runtime.CommonToken. The supported Antlr4 Action attributes are listed here. The start attribute is valid on a parser rule, but not on a token.
Note also that many of the token fields, including start, are protected. There are, however, corresponding getters defined in CommonToken -- start accessed by getStartIndex().